Skip to content

Home

Jump to bottom
lianneparkhouse edited this page Jan 31, 2024 · 17 revisions

Welcome to the jules-lsm.github.io wiki!

The JULES documentation is contained in the doc project of this repository. This wiki describes how to build the JULES User Guide, and update it to reflect your development.

Introduction

The JULES User Guide is built using the Sphinx Documentation Generator. The documentation is written in plain text files using a markup language called reStructuredText. These files are contained in the directory source and have the extension .rst. Sphinx can take these plain 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.

The JULES User Guide uses some custom extensions to reStructuredText to allow it to represent Fortran namelists more effectively - these are discussed in more detail below. Other than that, the Sphinx documentation is an excellent resource.

Checking out a copy of the JULES documentation

First time developers will need to clone the repository before starting work:

cd <path_to_where_you_want_to_clone_to> 
git clone git@github.com:jules-lsm/jules-lsm.github.io.git 
cd jules-lsm.github.io

  • Create and checkout a new feature branch:

    git checkout -b <feature_branch_name>

  • Share the feature branch to GitHub:

    git push --set-upstream origin <feature_branch_name>

  • Add files to the staging area using the git add <file_name> command:

    git add <file_name>

  • Commit all staged changes:

    git commit -m "<descriptive_commit_message>"

  • Share the changes to GitHub:

    git push

Create a pull request

Building the JULES User Guide

  • For first time users, please create the production environment to build the documentation. From the top level of the repository run:
conda env create -f environment.yml
  1. Activate the environment:
conda activate jules-user-guide
  1. Move to the correct directory:
cd <path_to>/jules-lsm.github.io/user_guide/doc

  1. Run make to build the documentation:

    • To build and view the HTML documentation: 
      make html
firefox build/html/index.html
    • To build and view the PDF documentation: 
      make latexpdf
evince build/latex/JULES_User_Guide.pdf

reStructuredText Extension for Fortran Namelists

The JULES User Guide uses a custom extension to reStructuredText to allow a more natural expression of Fortran namelists (see user_guide/doc/sphinxext/sphinx_nml_domain.py​ if you are interested in the implementation).

Documenting namelists

To begin documenting a namelist, the directive

.. nml:namelist:: <NAMELIST_NAME>

is used. By convention, namelist names are UPPER_CASE, while namelist member names are lower_case.

The nml:namelist directive does not output anything, but indicates that all subsequently declared members belong to the namelist (up until the next occurrence of nml:namelist).

Once a namelist has been declared, the members of that namelist are documented using the directive

.. nml:member:: <member_name>

   :type: [e.g. real, integer, logical]
   :permitted: [Permitted values, e.g. > 0, 1-5]
   :default: [Default value]

   First paragraph describing this namelist member.

   Second paragraph describing this namelist member.

   ...

The white-space (indentation and blank lines) is very important here. The :permitted: annotation is optional, and can be omitted if any value is acceptable. If the member has no default value, :default: None should be used. The description of the namelist member can contain any valid reStructuredText markup, as long as it is indented correctly.

The final directive used to document namelists is:

.. nml:group:: <Text describing the group>

   .. nml:member:: <member1>

      <Description of member1>

   .. nml:member:: <member2>

      <Description of member2>

nml:group is used to group logically related members within a namelist. Any number of members can be contained within it, but they must be indented. Any un-indented members end the group.

For an example of how nml:group might be used, see the documentation of JULES_INPUT_GRID in model_grid.nml. To see how the nml:group directive is rendered, see JULES_INPUT_GRID namelist members.

Note - If you are adding a completely new namelist then the namelist name also needs to be added to the contents page in source/namelists/contents.rst in order for it to be included in the build.

Cross-referencing namelists and namelist members

The custom reStructuredText extension for Fortran namelists also provides facilities for easily cross-referencing namelists and namelist members from anywhere in the User Guide.

To insert a cross-reference to a namelist anywhere in the documentation, use the following within any normal piece of text:

:nml:lst:`<NAMELIST_NAME>`

Similarly, to cross-reference a namelist member:

:nml:mem:`<NAMELIST_NAME>::<member_name>`

So to link to the member l_aggregate of namelist JULES_SURFACE, I would use the following:

This is some text, with a link to :nml:mem:`JULES_SURFACE::l_aggregate` embedded.

The cross-references are rendered as hyperlinks in the html version, and link to different parts of the document in the pdf version.

Checking from broken hyperlinks

One can test whether there are broken hyperlinks in the user guide by running

make linkcheck
Clone this wiki locally