To build the documentation, ensure you have both tox and pandoc installed. Then run the following from the repository root directory:
$ tox -e docs
Open docs/_build/html/index.html in a browser to view the docs.
Alternatively, to build the docs in a virtual environment rather than using tox, first ensure you have the necessary requirements installed:
$ pip install -r notebooks/requirements.txt -c notebooks/constraints.txt
$ pip install -r docs/requirements.txt -c docs/constraints.txtAnd then run make html in the docs subdirectory.
Any errors in the notebooks or API documentation markup will result in documentation build errors that must be fixed. To fix these, ensure that all new documentation is valid reST markup.
Note that since the API documentation is generated from inline Python docstrings,
the line numbers in any API error logs refer to generated reST files,
not the original Python source files. You can find these generated reST files
at docs/autoapi.
To save time, you can build just the API documentation (ignoring the notebooks) by
setting up a virtual environment as described above and running the following from the
docs subdirectory. Note that this will report warnings about the missing notebooks,
which you can ignore.
$ sphinx-build -M html . _build -D exclude_patterns=_build,Thumbs.db,.DS_Store,notebooksThe easiest way to test a specific notebook for Python errors is to run it with python
or in jupyter-notebook, as described in the notebooks README. However,
if you wish to build the documentation for a specific notebook, you can run something like
the following command to exclude all other notebooks and the API documentation:
$ sphinx-build -M html . _build -D autoapi_dirs= -D exclude_patterns=_build,Thumbs.db,.DS_Store,notebooks/[a-su-z]*For continuous integration, we save time by executing only dummy runs of the notebook optimization loops (the notebooks are still executed in full after merging). To do this locally, you can run the following:
$ tox -e quickdocsThese partial runs are managed by the
configuration in the docs/notebooks/quickrun subdirectory.
To run them in your own virtual environment, execute the following from the docs
subdirectory before building the documentation:
$ python notebooks/quickrun/quickrun.pyNote that this will modify the notebook files. To revert them to what they were before, you can execute the following:
$ python notebooks/quickrun/quickrun.py --revert