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
@@ -60,7 +60,7 @@ clone it to your local machine, and develop on a feature branch.
60
60
4. Create a ``feature`` branch to hold your development changes:
61
61
62
62
```bash
63
-
$ git checkout -b my-feature
63
+
git checkout -b my-feature
64
64
```
65
65
66
66
```{warning}
@@ -71,31 +71,31 @@ clone it to your local machine, and develop on a feature branch.
71
71
5. Project requirements are in ``requirements.txt``, and libraries used for development are in ``requirements-dev.txt``. To set up a development environment, you may (probably in a [virtual environment](https://docs.python-guide.org/dev/virtualenvs/)) run:
72
72
73
73
```bash
74
-
$ pip install -r requirements.txt
75
-
$ pip install -r requirements-dev.txt
76
-
$ pip install -r requirements-docs.txt # to generate docs locally
74
+
pip install -r requirements.txt
75
+
pip install -r requirements-dev.txt
76
+
pip install -r requirements-docs.txt # to generate docs locally
77
77
```
78
78
79
79
Alternatively, for developing the project in [Docker](https://docs.docker.com/), there is a script to setup the Docker environment for development. See {ref}`developing_in_docker`.
80
80
81
81
6. Develop the feature on your feature branch. Add your changes using git commands, ``git add`` and then ``git commit``, like:
82
82
83
83
```bash
84
-
$ git add modified_files
85
-
$ git commit -m "commit message here"
84
+
git add modified_files
85
+
git commit -m "commit message here"
86
86
```
87
87
88
88
to record your changes locally.
89
89
After committing, it is a good idea to sync with the base repository in case there have been any changes:
90
90
```bash
91
-
$ git fetch upstream
92
-
$ git rebase upstream/main
91
+
git fetch upstream
92
+
git rebase upstream/main
93
93
```
94
94
95
95
Then push the changes to your GitHub account with:
96
96
97
97
```bash
98
-
$ git push -u origin my-feature
98
+
git push -u origin my-feature
99
99
```
100
100
101
101
7. Go to the GitHub web page of your fork of the ArviZ repo. Click the 'Pull request' button to send your changes to the project's maintainers for review. This will send an email to the committers.
Copy file name to clipboardExpand all lines: doc/source/contributing/sphinx_doc_build.md
+44-10Lines changed: 44 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,56 @@
1
1
(sphinx_doc_build)=
2
2
# Building the documentation
3
3
4
-
The preferred workflow for contributing to ArviZ is to fork
5
-
the [GitHub repository](https://github.com/arviz-devs/arviz/),
6
-
clone it to your local machine, and develop on a feature branch. For a detailed description of the recommended development process, see the step-by-step guide {ref}`here <pr_steps>`.
4
+
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.
6
+
7
+
If you are not familiar with Python or have issues installing sphinx, you can skip
8
+
building the docs locally. Once you submit a pull request, a preview of the docs
9
+
will be built by readthedocs. The {ref}`preview_change` section at the bottom of
10
+
this page covers accessing this preview.
11
+
12
+
The reasons for the local build to be preferred over the readthedocs preview are:
13
+
***Faster**. The readthedocs preview needs to create and environment on which to install and run
14
+
sphinx _for every build_. On your local machine, the environment is created once and reused.
15
+
***Unlimited**. Readthedocs has limits on the number of builds a project can request.
16
+
If you push many commits in a short period of time (or there are people working on other PRs
17
+
at the same time as you) this limit will be triggered, and readthedocs won't generate any
18
+
preview for a while.
19
+
***Access to logs**. While working on the documentation, it is common to run into issues
20
+
and sphinx errors. If you build the documentation locally you will have access to all
21
+
the logs and error messages generated by python and sphinx. On the other hand, we only have
22
+
access to a subset of the logs from readthedocs, which can make troubleshooting harder.
7
23
8
24
If you are using Docker, see {ref}`building_doc_with_docker`.
9
25
10
-
## Pull request checks
26
+
## Using sphinx locally
27
+
ArviZ provides a `Makefile` to manage all doc building tasks.
28
+
29
+
### Base workflow: `make html`
30
+
To build the documentation you will need to execute `make html` on the command line.
11
31
12
-
Every PR has a list of checks that check if your changes follow the rules being followed by ArviZ docs.
13
-
You can check why a specific test is failing by clicking the `Details` next to it. It will take you to errors and warning page. This page shows the details of errors, for example in case of docstrings:
32
+
Once the command finishes, you can use `make preview` to open the generated documentation
33
+
on your browser.
14
34
15
-
`arviz/plots/pairplot.py:127:0: C0301: Line too long (142/100) (line-too-long)`.
35
+
Every time you make changes to the documentation you will need to run `make html` again.
36
+
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.
16
38
17
-
It means line 127 of the file `pairplot.py` is too long.
18
-
For running tests locally, see the {ref}`pr_checklist`.
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.
19
45
46
+
### Rebuild the docs from scratch: `make cleandocs`
47
+
In some cases, nor `make livehtml` nor re-executing `make html` multiple times will
48
+
serve to correctly update the documentation. This is common for example if working
49
+
on `conf.py` or making changes to the API docs.
50
+
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`
53
+
the documentation will be built from scratch (which will therefore be slower than usual).
20
54
21
55
(preview_change)=
22
56
## Previewing doc changes
@@ -43,4 +77,4 @@ For example, a warning box will look like this:
43
77
44
78
```{warning}
45
79
This page was created from a pull request (#PR Number).
0 commit comments