Sphinx Doc Primer

Basics

All docs should be placed under ./doc/ as a .md file in MarkDown format. As we are not currently documenting the API via Sphinx/Markdown do not worry about the sphinx-specific oddities for linking and referencing API objects. Standard markdown should work fine as is, including linking to other documents in the docs folder via:

[Link Name](linked-doc.md)
[Link to sub dir](utils/linked-doc.md)

Linking within docs is important, but the most important is the contents section of index.md. Following the MarkDown unordered list format is important as sphinx is currently setup to auto-generate a table of contents which will render on the left side of the HTML docs page listing. It will also automatically create next/previous topic buttons at the bottom of each page, in the order listed under the Contents section of index.md.

Note: GitHub Wiki-style doc linking by page title is not supported. So any wiki-converted docs will need to have all links updated.

Headers

As part of the automatic TOC generation, page header styling is extremely important. First to note that any H1 header in a *.md doc will show up in the table of contents. In This way, you can have multiple TOC entries from a single document. But it also means that all sub-headings in a doc need to be H2 or higher. Therefore, the first line of all docs must follow this pattern.

# Doc Main Title <DO NOT put text before this!>

Introduction Text

## Sub Section 1

Details text

## Sub Section 2

Details Text

# Optional Secondary TOC Header

Building Docs

Note: To do any of this you must first install the required docs packages: pip3 install -r ./doc/doc_requirements.txt

The docs will automatically be build by ReadTheDocs.org in the long term and will do so only for GitHub releases with the current configuration. So there's no worrying about docs for a random dev version being built. However, once v4.0 are released we will switch to the master branch being the latest and greatest dev, in which case ReadTheDocs will start building every new commit into master as unstable docs.

To build the documents, locally, however there are two main methods. In either way, the results will be available at ./doc/_build/html/index.html

First, you can run scripts/gen_docs.sh from the root of the repo, which will automatically create the bp command doc file and then generate the HTML output to the path listed above.

For continued docs updating, however, the automatic re-generation feature of sphinx is much easier and can be done as follows:

cd doc
make livehtml

This will continuously rebuild the documentation (about once every 30 seconds in practice) and automatically reload the page in the browser. Note, however, that this will not generate the bp command doc file, so the above method should be used at least once before using this option. If updates to the bp command docs are being made this option is not suitable.