Sphinx Documentation

The documentation is written in plain text files using a markup language called reStructuredText. The text files have the extension .rst. Sphinx can take these text files and generate both HTML and PDF documentation from them (complete with cross-referencing links, etc.). Since reStructuredText is a plain text format, your favourite text editor is all you need to edit the documentation.

Tip

The Sphinx documentation is a useful resource.

Building the documentation

Please create the production environment to build the documentation (first time users only), and then activate it.

JULES

From the top level of the repository:

conda env create -f environment.yml

Activate the environment:

conda activate jules-user-guide

LFRic Apps and Core

On the Met Office Azure Spice machine the main LFRic module environment contains all the required packages to build the documentation. Ensure this is loaded.

Note there is a style guide included in the LFRic Core documentation that should be followed for both these repositories.

Working Practices

From the top level of the repository:

conda env create -f env.yml

Activate the environment:

conda activate sphinx_doc_env

Move to the documentation directory and run make to build the documentation:

To build and view the HTML documentation:

make [clean] html
firefox build/html/index.html &

To build and view the PDF documentation:

make latexpdf
evince build/latex/JULES_User_Guide.pdf