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
to aid in presenting clear, concise, uniform notation across all documents related to this project. Similarly, a set of text macros are defined in
Please familiarize yourself with this list of macros before working on our documents and please use the macros consistently throughout all documentation.