Contributing to the Documentation¶
Documentation is important and we encourage any improvements that can be made. If you believe the documentation is not clear please contribute a change to improve the documentation for all users.
Any change to the Iris project whether it is a bugfix, new feature or documentation update must use the Development Workflow.
Requirements¶
The documentation uses specific packages that need to be present. Please see Installing Iris for instructions.
Building¶
The build can be run from the documentation directory iris/docs/iris/src
.
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 cirrus-ci 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 also an option to perform a build but skip the Gallery creation completely. This can be achieved via:
make html-noplot
If you wish to run a clean build you can run:
make clean
make html
This is useful for a final test before committing your changes.
Note
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.
Testing¶
There are a ways to test various aspects of the documentation. The
make
commands shown below can be run in the iris/docs/iris
or
iris/docs/iris/src
directory.
Each Gallery entry has a corresponding test. To run the tests:
make gallerytest
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:
make doctest
See iris.cube.Cube.data
for an example of using the doctest
approach.
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:
make linkcheck
If this fails check the output for the text broken and then correct or ignore the url.
Note
In addition to the automated cirrus-ci build of all the
documentation build options above, the
https://readthedocs.org/ service is also used. The configuration
of this held in a file in the root of the
github Iris project named
.readthedocs.yml
.
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
iris/docs/iris/src/sphinxext
. Once the make html
command has been run,
the output of these scripts can be found in
iris/docs/iris/src/generated/api
.
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
iris/docs/iris/src/sphinxext/generate_package_rst.py
file.
Gallery¶
The Iris Gallery uses a sphinx extension named sphinx-gallery that auto generates reStructuredText (rst) files based upon a gallery source directory that abides directory and filename convention.
The code for the gallery entries are in iris/docs/iris/gallery_code
.
Each sub directory in this directory is a sub section of the gallery. The
respective README.rst
in each folder is included in the gallery output.
For each gallery entry there must be a corresponding test script located in
iris/docs/iris/gallery_tests
.
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
iris/docs/iris/src/generated/gallery
.
For more information on the directory structure and options please see the sphinx-gallery getting started documentation.