Build documentation with Sphinx

This page describes how to build documentation locally for testing. This is not always needed. Our published documentation is built and released automatically when a new package version is released. In addition, every PR triggers automatic testing of the documentation build. However, those GitHub builds can take awhile and there doesn’t seem to be an easy way to actually view the built documentation. For those reasons, it is sometimes helpful to be able to build the documentation locally.

Follow the setup steps in Managing Dependencies with Poetry to create a conda environment with Poetry installed. Then:

# Install pittgoogle dependencies, including those in the "docs" group.
poetry install --with=docs

Now, cd to the docs directory and run make:

cd docs  # assuming we started in the repo root directory

# Build the documentation
make clean
make html

This should have created a file at docs/build/html/index.html. Open it in a browser to view the built documentation.