Building the documentation#
Before submitting a pull request check if your modifications have introduced new sphinx warnings by building the documentation locally and try to fix them.
pip install '.[doc]'
To build the documentation, you need to be in the docs folder:
cd docs
In the vast majority of cases, you only need to generate the web site without
the example gallery (equivalent to make html-noplot):
make
The documentation will be generated in the _build/html/ directory
and are viewable in a web browser, for instance by opening the local
_build/html/index.html file.
To also generate the example gallery you can use:
make html
This will run all the examples, which takes a while. You can also run only a few examples based on their file names. Here is a way to run all examples with filenames containing “dcrt”:
EXAMPLES_PATTERN="dcrt" make html
You can use regular expressions for more advanced use cases.
In the case of a PR, you can look at the version generated by circle ci, by looking at the details of Check the rendered docs here!.
Debugging the documentation#
- Docstring of functions:
For any errors or warnings in the doctring, the best way to fix it is to copy the doctring in a file and use the command rst2html. This command is provided by sphinx.
- Example error with sphinx gallery:
If there is an error which appears when the documentation is generated and not when the example is run alone, In this case, you should use the file documentation/debbugger_script/run_debug_example.py