This directory contains the sources (.md
and .rst
files) for the
documentation. The main index page is defined in source/index.rst
.
The Sphinx options and plugins are found in the source/conf.py
file.
The documentation is generated in full by calling make html
which
also automatically generates the Python API documentation from
docstrings.
Dependencies must be installed using make sync
from the project root.
Run make docs-build
from project root, or make html
from the docs/
subfolder (this one).
Note this can take some time as some of the notebooks may be executed
during the build process. The resulting documentation is located in the
_build
directory with _build/html/index.html
marking the homepage.
We use various Sphinx extensions and plugins to build the documentation:
- recommonmark - to handle both
.rst
and.md
- sphinx.ext.napoleon - support extracting Numpy style doctrings for API doc generation
- sphinx_autodoc_typehints - support parsing of typehints for API doc generation
- sphinxcontrib.apidoc - automatic running of sphinx-apidoc during the build to document API
- nbsphinx - parsing Jupyter notebooks to generate static documentation
- nbsphinx_link - support linking to notebooks outside of Sphinx source directory via
.nblink
files
The full list of plugins and their options can be found in source/conf.py
.