Building the Docs

This documentation is generated using Sphinx and authored in Markdown. Markdown support for Sphinx is provided by MyST. MyST provides a number of small syntax extensions to support declaring ReStructuredText directives; see the MyST syntax guide for details.

In order to build the devloper documentation:

  1. Install PlantUML. On macOS, this can be done via brew install plantuml.

  2. Install the requirements for Sphinx:

    $ pip install requirements.txt

  3. Run make to build the HTML documentation:

    $ make

This will regenerate any out-of-date SVGs and build the a local version of the HTML documentation. The documentation can also be built from the repository root by running make developer_docs.

Note that Sphinx doesn’t do a great job of rebuilding output files if only the table-of-contents has changed. If you change the table of contents, you may need to clean the output directory in order to see the effects of your changes:

```bash
$ make clean
```

Notes on Style