(sphinx_doc_build)=
# Building the documentation

The preferred way to build the documentation for any ArviZ package
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.

## Using sphinx locally
ArviZ uses [tox](https://tox.wiki/en/latest/index.html) to help with common development related tasks.

### Base workflow
To build the documentation you will need to execute the following instructions on the command line:

```bash
tox -e docs      # build docs with sphinx
tox -e viewdocs  # view docs in browser
```

Every time you make changes to the documentation you will need to run `tox -e docs` again.
However, if you haven't closed the documentation page that was open in the browser, you
will be able to skip the `tox -e viewdocs` command.

### Live preview workflow
As calling `tox -e docs` every time you make changes can be annoying,
it is also possible to generate a live preview of the documentation website
that updates automatically whenever you make a change.

```bash
tox -e livedocs
```

### Rebuild the docs from scratch
In some cases, nor `tox -e livedocs` nor re-executing `tox -e docs` multiple times 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 run **`tox -e cleandocs`**. This will clean all the cache
and intermediate files so the next time you run `tox -e docs` or `tox -e livedocs`
the documentation will be built from scratch (which will therefore be slower than usual).

(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](https://readthedocs.org) to automatically build the documentation.

Whenever a PR is opened on any ArviZ repository the `read-the-docs-community` bot
will comment on it with a link to the documentation preview.

Note however that this can only happen if the documentation could be built successfully.
To check for the status or see the error logs in case of failure, search for
the `docs/readthedocs.org:arviz` check.