Yarrow's documentation is built using sphinx and hosted on readthedocs.
To build documentation locally, you will need sphinx and some extensions. Set up a separate virtual environment to build docs as follows:
python3 -m venv docs.venv
source docs.venv/bin/activate
pip install -r docs/requirements.txt
Then build the docs using the Makefile:
cd docs
make html
The sphinx documentation source files can be found in
./docs/source.
The top-level documentation file is index.rst, which generates the page you
see when you visit
readthedocs.
Other top-level sections can be found in their corresponding .rst files.
The api_reference.rst file uses
autosummary to generate an API reference from docstrings.
In order to get detailed module pages, there's a template file in
docs/source/_templates/autosummary/module.rst
which tells sphinx how to generate the documentation for each module.
Sometimes autosummary's autogenerated .rst files can sometimes survive even
after a make clean.
If you're running into strange errors, it can help to run the following from within ./docs.
make clean
rm -r source/_autosummary
make html