Build documentation locally

Warning

Docs build is not supported on Windows. To build docs on Windows we recommend running inside a Docker container.

To build the docs, first install dependencies by running these commands at the PyMC repo root:

# create the pymc-docs conda env, or equivalently make
# sure all dependencies listed in this file are installed
conda env create -f conda-envs/environment-docs.yml

# Install local pymc version in editable mode
pip install -e .

Building the documentation

There is a Makefile in the pymc repo to help with the doc building process.

make clean
make html

make html is the command that builds the documentation with sphinx-build. make clean deletes caches and intermediate files.

The make clean step is not always necessary. If you are working on a specific page, for example, then you can rebuild the docs without the clean step, and everything should work fine. If you are restructuring the content or editing toctrees, then you’ll need to execute make clean.

A good approach is generally to skip make clean, which makes the make html faster, and see how everything looks. If something looks strange, run make clean and make html one after the other to see if it fixes the issue before checking anything else.

Emulate building on readthedocs

The target rtd is also available to chain make clean with sphinx-build setting also some extra options and environment variables to instruct sphinx to simulate a readthedocs build as much as possible.

make rtd

Important

This won’t reinstall or update any dependencies, unlike on readthedocs where all dependencies are installed in a clean env before each build.

But it will execute all notebooks inside the core_notebooks folder, which by default are not executed. Executing the notebooks will add several minutes to the doc build, as there are 6 notebooks which take between 20s to 5 minutes to run.

View the generated docs

make view

This will use Python’s webbrowser module to open the generated website on your browser. The generated website is static, so there is no need to set a server to preview it.