Skip to content

Commit bf359c2

Browse files
committed
TL: added contrib section on documentation generation
1 parent 9cad0f0 commit bf359c2

File tree

1 file changed

+22
-2
lines changed

1 file changed

+22
-2
lines changed

docs/contrib/02_continuous_integration.md

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Continuous Integration in pySDC
22

33
Any commit in `pySDC` are tested within by GitHub continuous integration (CI). You can see in in the [action panel](https://github.com/Parallel-in-Time/pySDC/actions) the tests for each branches.
4-
Those tests can be divided in two main categories : code linting and code testing.
4+
Those tests can be divided in two main categories : [code linting](#code-linting) and [code testing](#code-testing).
5+
Finally, the CI also build artifacts that are used to generate the documentation website (see http://parallel-in-time.org/pySDC/), more details given in the [documentation generation](#documentation-generation) section.
56

67
## Code linting
78

@@ -29,7 +30,7 @@ Some style rules that are automatically enforced :
2930
- lines should be not longer than 120 characters
3031
- arithmetic operators (`+`, `*`, ...) should be separated with variables by one empty space
3132
32-
# Code testing
33+
## Code testing
3334
3435
This is done using[ `pytest`](https://docs.pytest.org/en/7.2.x/), and runs all the tests written in the `pySDC/tests` folder. You can run those locally in the root folder of `pySDC` using :
3536
@@ -47,5 +48,24 @@ pytest -v pySDC/tests
4748
> pytest -v pySDC/tests/test_nodes.py # only test nodes generation
4849
> ```
4950
51+
## Documentation generation
52+
53+
To check the documentation generation, you can wait for all the CI tasks to download the `docs` artifacts, unzip it and open the `index.html` file there with you favorite browser. However, when you are working on documentation (of the project, of the code, etc ...), you can already build and check the website locally :
54+
55+
```bash
56+
# Run all tests, continuing even with errors
57+
pytest --continue-on-collection-errors -v --durations=0 pySDC/tests
58+
# Generate rst files for sphinx
59+
./docs/update_apidocs.sh
60+
# Generate html documentation
61+
sphinx-build -b html docs/source docs/build/html
62+
```
63+
64+
Then you can open `docs/build/html/index.html` using you favorite browser and check how your own documentation looks like on the website.
65+
66+
> :bell: **Important** : running all the tests is necessary to generate graphs and images used by the website.
67+
> But you can still generate the website without it : just all images for the tutorials, projects and playgrounds will be missing.
68+
> This approach can be considered for local testing of your contribution when it does not concern parts containing images (_i.e_ project or code documentation).
69+
5070
:arrow_left: [Back to Pull Request Recommendation](./01_pull_requests.md) ---
5171
:arrow_right: [Next to Naming Conventions](./03_naming_conventions.md)

0 commit comments

Comments
 (0)