Updating the Documentation

The documentation is written in reStructuredText format and is built using Sphinx.

Sphinx was chosen for it’s ease of use and ability to:

easily generate a navigation bar and index.
easily add cross references to other parts of the documentation.
support for the more advanced documentation requirements for some of the pipeline pattern and feature documentation.

Source Files

The source files for the documentation are located in the docs/source directory.

Writing Documentation

If a new feature is added or change to existing feature, ensure the feature is well documented in a new feature file or update the existing feature file with the name feature_<feature_name>.rst and add it to the Framework Features page. - In the feature file, include:
- Feature description
- Configuration options
- Usage examples / sample code
Update Data Flow Spec reference where applicable

Styling

Styling for the documentation which controls the look of the html output is in two main locations

The theme and options that are used to generate the html output is defined in the conf.py file. The existing theme should not be changed unless there is an agreement on a new theme.
- More information on theming can be found here: https://www.sphinx-doc.org/en/master/usage/theming.html
- The available html output options can be found here: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
Custom styling can be found in the custom.css file which can be found in the docs/_static directory.
- More information on how to add custom CSS can be found here: https://docs.readthedocs.com/platform/stable/guides/adding-custom-css.html#overriding-or-replacing-a-theme-s-stylesheet

Generating the Documentation

Supported Formats

Sphinx has been configured to generate the following formats:

HTML
Markdown

Dependencies

To install the dependencies, ensure that the following command dev step up is executed and if not run the following command in the root directory of the repository:

pip install -r requirements-dev.txt

Building the Documentation

The Framework comes with a make file to build the documentation. There is one for Bash and one for Windows.

To build the documentation, run the following command in the docs directory:

HTML:
make html
Markdown:
make md

The above commands will build the documentation and save it in the docs/build directory.

To view the documentation, open the below files in your browser.:

HTML: docs/build/html/index.html
Markdown: docs/build/markdown/index.md

Clean the Documentation

Sometimes it will be necessary to delete the build directory and re-build the documentation. To do this, run the following command in the docs directory:

make clean