Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Sphinx Doc Primer
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
Note: GitHub Wiki-style doc linking by page title is not supported. So any wiki-converted docs will need to have all links updated.
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
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
To build the documents, locally, however there are two main methods. In either way, the results will be available at
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.