3. Documentation

3.1. Tools

A GitHub action is run automatically to check for typographic errors in all documentation in the repository using the typos tool with our typos.toml configuration file. An associated typos command line tool can also be installed locally by developers for checking eagerly for mistakes:

$ cd /path/to/OpenBT
$ typos --config=typos.toml

Another GitHub action automatically checks the documentation for broken links using the tool lychee and its .lycheeignore configuration file. An associated lychee command line tool can also be installed locally by developers for checking eagerly for mistakes:

$ cd /path/to/OpenBT
$ lychee -v .

Please read the link checking action to determine if extra flags should be provided.

3.2. Guides

The User Guides and the Developer Guide are all developed in a single Sphinx project within the docs folder, which facilitates publication via Read the Docs. The guides’ contents are presently assembled from files only in docs, which are written in reStructuredText.

Refer to the Developer Environment section to find more information about rendering HTML- and PDF-format version of the documentation locally.

Todo

Should the docstrings in the Python package be updated so that their contents generate low-level API docs for the Python User Guide?

3.3. Macro Definitions

Common and OpenBT-specific LaTeX math mode macros are defined in

• docs/latex_macros_base.json

• docs/latex_macros_notation.json

to aid in presenting clear, concise, uniform notation across all documents related to this project. Similarly, a set of text macros are defined in

• docs/sphinx_macros.json

Please familiarize yourself with this list of macros before working on our documents and please use the macros consistently throughout all documentation.