Contributing to the Documentation#
This guide is for those comfortable with the development process, looking for the specifics of how to apply that knowledge to Iris. You may instead find it easier to use the Contributing to the Documentation (the easy way).
Any change to the Iris project whether it is a bugfix, new feature or documentation update must use the Development Workflow.
The documentation uses specific packages that need to be present. Please see Installing for instructions.
This documentation was built using the latest Python version that Iris supports. For more information see Installing.
The build can be run from the documentation directory
The build output for the html is found in the
_build/html sub directory.
When updating the documentation ensure the html build has no errors or
warnings otherwise it may fail the automated Iris GitHub Actions build.
Once the build is complete, if it is rerun it will only rebuild the impacted build artefacts so should take less time.
There is an option to perform a build but skip the Gallery creation completely. This can be achieved via:
Another option is to skip the Iris API documentation creation. This can be useful as it reduces the time to build the documentation, however you may have some build warnings as there maybe references to the API documentation. This can be achieved via:
If you wish to run a full clean build you can run:
make clean make html
This is useful for a final test before committing your changes. Having built the documentation, you can view them in your default browser via:
In order to preserve a clean build for the html, all warnings
have been promoted to be errors to ensure they are addressed.
This only applies when
make html is run.
There are various ways to test aspects of the documentation.
Each Gallery entry has a corresponding test. To run all the gallery tests:
pytest -v docs/gallery_tests/test_gallery_examples.py
To run a test for a single gallery example, use the
pytest -k option for
pattern matching, e.g.:
pytest -v -k plot_coriolis docs/gallery_tests/test_gallery_examples.py
make commands shown below can be run in the
Many documentation pages includes python code itself that can be run to ensure it is still valid or to demonstrate examples. To ensure these tests pass run:
The hyperlinks in the documentation can be checked automatically.
If there is a link that is known to work it can be excluded from the checks by
adding it to the
linkcheck_ignore array that is defined in the
conf.py. The hyperlink check can be run via:
If this fails check the output for the text broken and then correct or ignore the url.
Generating API Documentation#
In order to auto generate the API documentation based upon the docstrings a
custom set of python scripts are used, these are located in the directory
docs/src/sphinxext. Once the
make html command has been run,
the output of these scripts can be found in
If there is a particularly troublesome module that breaks the
make html you
can exclude the module from the API documentation. Add the entry to the
exclude_modules tuple list in the
The code for the gallery entries are in
Each sub directory in this directory is a sub section of the gallery. The
README.rst in each folder is included in the gallery output.
For each gallery entry there must be a corresponding test script located in
To add an entry to the gallery simple place your python code into the
appropriate sub directory and name it with a prefix of
plot_. If your
gallery entry does not fit into any existing sub directories then create a new
directory and place it in there.
The reStructuredText (rst) output of the gallery is located in
For more information on the directory structure and options please see the sphinx-gallery getting started documentation.