You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The preferred way to build the ArviZ documentation when making changes to the website is doing
5
-
so locally with sphinx. This how-to guide explains the steps to build the ArviZ docs locally.
4
+
The preferred way to build the documentation for any ArviZ package
5
+
when making changes to the website is doing so locally with sphinx.
6
+
This how-to guide explains the steps to build the ArviZ docs locally.
6
7
7
8
If you are not familiar with Python or have issues installing sphinx, you can skip
8
9
building the docs locally. Once you submit a pull request, a preview of the docs
@@ -21,60 +22,48 @@ The reasons for the local build to be preferred over the readthedocs preview are
21
22
the logs and error messages generated by python and sphinx. On the other hand, we only have
22
23
access to a subset of the logs from readthedocs, which can make troubleshooting harder.
23
24
24
-
If you are using Docker, see {ref}`building_doc_with_docker`.
25
-
26
25
## Using sphinx locally
27
-
ArviZ provides a `Makefile`to manage all doc building tasks.
26
+
ArviZ uses [tox](https://tox.wiki/en/latest/index.html)to help with common development related tasks.
28
27
29
-
### Base workflow: `make html`
30
-
To build the documentation you will need to execute `make html`on the command line.
28
+
### Base workflow
29
+
To build the documentation you will need to execute the following instructions on the command line:
31
30
32
-
Once the command finishes, you can use `make preview` to open the generated documentation
33
-
on your browser.
31
+
```bash
32
+
tox -e docs # build docs with sphinx
33
+
tox -e viewdocs # view docs in browser
34
+
```
34
35
35
-
Every time you make changes to the documentation you will need to run `make html` again.
36
+
Every time you make changes to the documentation you will need to run `tox -e docs` again.
36
37
However, if you haven't closed the documentation page that was open in the browser, you
37
-
will be able to skip the `make preview` command.
38
+
will be able to skip the `tox -e viewdocs` command.
38
39
39
-
### Live preview workflow: `make livehtml`
40
-
As calling `make html` every time you make changes can be annoying, it is also possible
41
-
to install [sphinx-autobuild](https://github.com/executablebooks/sphinx-autobuild)
42
-
with `pip install sphinx-autobuild` and then execute
43
-
`make livehtml` on the command line. With that, the documentation will be rebuilt every
44
-
time you save a doc related file.
40
+
### Live preview workflow
41
+
As calling `tox -e docs` every time you make changes can be annoying,
42
+
it is also possible to generate a live preview of the documentation website
43
+
that updates automatically whenever you make a change.
45
44
46
-
### Rebuild the docs from scratch: `make cleandocs`
47
-
In some cases, nor `make livehtml` nor re-executing `make html` multiple times will
45
+
```bash
46
+
tox -e livedocs
47
+
```
48
+
49
+
### Rebuild the docs from scratch
50
+
In some cases, nor `tox -e livedocs` nor re-executing `tox -e docs` multiple times will
48
51
serve to correctly update the documentation. This is common for example if working
49
52
on `conf.py` or making changes to the API docs.
50
53
51
-
When that happens, you will need to run `make cleandocs`. This will clean all the cache
52
-
and intermediate files so the next time you run `make html` or `make livehtml`
54
+
When that happens, you will need to run **`tox -e cleandocs`**. This will clean all the cache
55
+
and intermediate files so the next time you run `tox -e docs` or `tox -e livedocs`
53
56
the documentation will be built from scratch (which will therefore be slower than usual).
54
57
55
58
(preview_change)=
56
59
## Previewing doc changes
57
60
58
-
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.
59
-
For previewing documentation changes, take the following steps:
60
-
61
-
1. Go to the checks of your PR. Wait for the `docs/readthedocs.org:arviz` to complete.
61
+
There is an easy way to check the preview of docs by opening a PR on GitHub.
62
+
ArviZ uses [ReadTheDocs](https://readthedocs.org) to automatically build the documentation.
62
63
63
-
```{note}
64
-
The green tick indicates that the given check has been built successfully.
65
-
```
64
+
Whenever a PR is opened on any ArviZ repository the `read-the-docs-community` bot
65
+
will comment on it with a link to the documentation preview.
66
66
67
-
2. Click the `Details` button next to it.
68
-
3. It will take you to the preview of ArviZ docs of your PR.
69
-
4. Go to the webpage of the file you are working on.
70
-
5. Check the preview of your changes on that page.
71
-
72
-
```{note} Note
73
-
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.
74
-
```
75
-
76
-
For example, a warning box will look like this:
77
-
78
-
```{warning}
79
-
This page was created from a pull request (#PR Number).
80
-
```
67
+
Note however that this can only happen if the documentation could be built successfully.
68
+
To check for the status or see the error logs in case of failure, search for
0 commit comments