Skip to content

sphinx_doc_build.md

Latest commit

 

History

History
92 lines (70 loc) · 3.89 KB

sphinx_doc_build.md

File metadata and controls

92 lines (70 loc) · 3.89 KB

(sphinx_doc_build)=

Building the documentation

The preferred way to build the ArviZ documentation when making changes to the website is doing so locally with sphinx. This how-to guide explains the steps to build the ArviZ docs locally.

If you are not familiar with Python or have issues installing sphinx, you can skip building the docs locally. Once you submit a pull request, a preview of the docs will be built by readthedocs. The {ref}preview_change section at the bottom of this page covers accessing this preview.

The reasons for the local build to be preferred over the readthedocs preview are:

  • Faster. The readthedocs preview needs to create and environment on which to install and run sphinx for every build. On your local machine, the environment is created once and reused.
  • Unlimited. Readthedocs has limits on the number of builds a project can request. If you push many commits in a short period of time (or there are people working on other PRs at the same time as you) this limit will be triggered, and readthedocs won't generate any preview for a while.
  • Access to logs. While working on the documentation, it is common to run into issues and sphinx errors. If you build the documentation locally you will have access to all the logs and error messages generated by python and sphinx. On the other hand, we only have access to a subset of the logs from readthedocs, which can make troubleshooting harder.

If you are using Docker, see {ref}building_doc_with_docker.

Using sphinx locally

ArviZ uses sphinx directly to manage all doc building tasks.

Base workflow: sphinx-build

To build the documentation you will need to execute the following command from the repository root on the command line:

sphinx-build -b html docs/source docs/build/html

Once the command finishes, you can open the generated documentation by opening docs/build/html/index.html in your browser.

Every time you make changes to the documentation you will need to run the command again.

Live preview workflow:

As rebuilding the documentation every time you make changes can be annoying, it is also possible to install sphinx-autobuild with pip install sphinx-autobuild and then execute the following command from the repository root on the command line. With that, the documentation will be rebuilt every time you save a doc related file.

sphinx-autobuild docs/source docs/build/html

Rebuild the docs from scratch:

In some cases, nor re-running the documentation build command nor using a live preview will serve to correctly update the documentation. This is common for example if working on conf.py or making changes to the API docs.

When that happens, you will need to remove the build directory and rebuild the documentation from scratch so the next build starts from a clean state :

rm -rf docs/build
sphinx-build -b html docs/source docs/build/html

(preview_change)=

Previewing doc changes

There is an easy way to check the preview of docs by opening a PR on GitHub. ArviZ uses readthedocs to automatically build the documentation. For previewing documentation changes, take the following steps:

  1. Go to the checks of your PR. Wait for the docs/readthedocs.org:arviz to complete.

    The green tick indicates that the given check has been built successfully.

  2. Click the Details button next to it.

  3. It will take you to the preview of ArviZ docs of your PR.

  4. Go to the webpage of the file you are working on.

  5. Check the preview of your changes on that page.

The preview version of ArviZ docs will have a warning box that says "This page was created from a pull request (#Your PR number)." It shows the PR number whose changes have been implemented.

For example, a warning box will look like this:

This page was created from a pull request (#PR Number).