Building the Documentation

We use Sphinx and Read The Docs to semi-automatically build and host our documentation.

Sphinx is tightly integrated with the Python programming language and needs to be able to import and parse the source code to do its job. Thus, it also needs to be able to create an appropriate python environment. This process is controlled by docs/

If you are editing the documentation and need to regenerate the outputs as you go to see your changes reflected locally, the most reliable option is to use Tox. Tox will remove the previously generated outputs and regenerate everything from scratch:

$ tox -e docs

If you’re just working on a single page and don’t care about the entire set of documents being regenerated and linked together, you can call Sphinx directly:

$ sphinx-build -b html docs docs/_build/html

This will only update any files that have been changed since the last time the documentation was generated.

To view the documentation that’s been output at HTML, you’ll need to open the docs/_build/html/index.html file within the PUDL repository with a web browser. You may also be able to set up automatic previewing of the rendered documentation in your text editor with appropriate plugins.


Some of the documentation files are dynamically generated. We use the sphinx-apidoc utility to generate RST files from the docstrings embedded in our source code, so you should never edit the files under docs/api. If you create a new module, the corresponding documentation file will also need to be checked in to version control.

Similarly the PUDL Data Dictionary is generated dynamically by the pudl.convert.metadata_to_rst script that gets run by Tox when it builds the docs.