Documentation Generation

This is a component of the Documentation Guide.

AFSIM supports automatic documentation generation (conversion from RST source to a final output format - i.e. HTML).

The generation process is automated through the use of the following tools:

  • CMake

  • Sphinx

  • Python

Note

Additional tools may be necessary to generate documentation in alternative formats. For more information see Prerequisites

The following sections include developer-focused instructions which detail multiple methods to generate AFSIM Documentation.

Organization & CMake

Any project that is included by CMake in the AFSIM build system may have documentation automatically generated. Sphinx will look for directories named doc in the list of directories supplied to the add_wsf_doc_input macro from a project’s CMakeList file. Any ‘.rst’ files included in the doc directory and its subdirectories will automatically be included in the documentation build.

Example directory structure:

wsf_extension
|__ doc
|__ grammar
|__ source
|__ test
|__ CMakeLists.txt
|__ wsf_cmake_extension.cmake
|__ wsf_module

Within CMakeLists.txt:

# Add *doc* parent directory to the documentation build list
add_wsf_doc_input(${CMAKE_CURRENT_SOURCE_DIR})

Building HTML Documentation

Generating the HTML documentation is as simple as building the DOCUMENTATION target generated by CMake.

  • In Microsoft Visual Studio right click on DOCUMENTATION in the Solution Explorer under the CMakeTargets folder and select Build.

  • On Linux, from within the build directory, enter make DOCUMENTATION.

  • The CMake command-line interface may also be used to build the DOCUMENTATION target:

    cmake --build <build-dir> --target DOCUMENTATION

The resulting documentation can be viewed by opening the file <build-dir>/documentation/index.html.

For convenience, index.html is added to the DOCUMENTATION Visual Studio project after generation, and may be opened from there.

Sphinx will attempt to rebuild an HTML file only if the corresponding ‘.rst’ file is newer. However, it does not perform extensive dependency analysis.

Tip

If the resulting output does not reflect the expected result, remove the _doctrees, docs and html directories in the <build-dir>/documentation directory and re-build the DOCUMENTATION target.

Building Documentation without CMake

AFSIM documentation may be generated without CMake by executing the cmake/Modules/sphinx/build_doc.py script like:

python3 cmake/Modules/sphinx/build_doc.py

By default this script will glob the contents of all doc directories within the AFSIM source tree, and emit generated documentation in the cmake/Modules/sphinx/generated-docs directory. Available command line options may be viewed with build_doc.py --help.

Note

The build_doc.py script is a convenient mechanism for testing AFSIM documentation, however the CMake method is the primary mechanism. The CMake approach provides full functionality (i.e. populating sidebar entries) and more convenient customization options to select a subset of documentation modules to be generated.