:orphan:

.. ****************************************************************************
.. CUI
..
.. The Advanced Framework for Simulation, Integration, and Modeling (AFSIM)
..
.. The use, dissemination or disclosure of data in this file is subject to
.. limitation or restriction. See accompanying README and LICENSE for details.
.. ****************************************************************************

Documentation Generation
========================

This is a component of the :doc:`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 :ref:`docs/developer/build_instructions: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:

   .. parsed-literal::

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

Within ``CMakeLists.txt``:

   .. code-block::

      # 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.