Distribution Statement

# # # This source code is subject to the license referenced at

# # # NRLMMD-GEOIPS.

Documentation Builder

We use Sphinx, pinkrst and brassy to build our documentation. For more information on how to use the documentation builder, see Documentation Building.

Mechanism

The build script does the following actions in the following order:

1. Validates the provided repo_path exists and is a git directory

2. Verifies the provided package_name is installed

3. Copies build files to a temporary build directory that is deleted after the program exits

4. Copies non-documentation files (eg. CODE_OF_CONDUCT.md) into a special import directory at the top of the docs directory for access during building

5. If building documentation for a plugin (aka package_name is not geoips), it copies static files from the GeoIPS documentation directory that are needed for building

6. Generates a top level index.rst from index.template.rst and replaces placeholder strings with actual section paths or removes them depending if those sections are present in the documentation.

7. Builds release notes with brassy from sub-directories of the releases directory (any sub-directory named upcoming is skipped as a special case for the release process)

8. A release index file is generated that indexes the newly generated and old .rst files in releases/

9. Sphinx’s apidoc tool is used to generate .rst files for the packages Python modules

10. Sphinx is used to build html files from the generated .rst files

11. If everything succeeds, the built html files are copied to the specified output directory