The source for the documentation can be found in the
directory of this repository. These source files are a combination of
ReStructured Text (rst) and Jupyter notebooks.
Editing source files¶
- ReStructured Text: The rst files should be fairly straightforward to edit. Here is a quick reference of rst syntax. Some of the rst files also use Sphinx autodoc.
- Jupyter Notebooks: The Jupyter notebooks are written in Python and should be written so that they are compatible with both Python 2 and Python 3. If you need to reference another part of the documentation from a notebook, you will need to put that reference in a raw cell in the notebook, not a markdown cell.
Adding a new file to documentation¶
If you add a new file (either rst or ipynb) make sure to link to it from the
Additionally, if you are adding a new notebook in the user guide, please add
the rst version of it to
Building documentation locally¶
If you have made changes to the user guide or other notebooks that need to be executed, please make sure you re-run all the documentation before committing. While the documentation gets built automatically on Read The Docs, the notebooks do not get execute by Read The Docs – they must be executed manually. However, executing the notebooks is easy to do!
python tasks.py docs
This will perform a few different steps:
- The notebooks are executed and converted to rst or html (the actual
documentation notebooks will be converted to rst, and example notebooks will
be converted to html) using the
- The command line documentation is automatically generated using the
- The rst files are converted to html using Sphinx.
python tasks.py docs, the resultant HTML files will be in
docs/build/html. You can open these files in your browser to preview what
the documentation will look like (note, however, that the theme used by Read
The Docs is different from the default Sphinx theme, so the styling will look