build.md

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

• Do use appropriate links wherever possible. Learn to use header anchors.
• If a particular link destination is referenced multiple times, prefer shortcut reference links.