Skip to content

Update jules doc section and fix typos #611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
James Bruten (james-bruten-mo) merged 1 commit into from
Apr 1, 2026
Merged

Update jules doc section and fix typos #611

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions source/Development/jules_docs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,10 @@ 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 `doc/sphinxext/sphinx_nml_domain.py`_ if you are interested in
the implementation).
(see `doc/sphinxext/sphinx_nml_domain.py`_ if you are interested in the
implementation).

.. doc/sphinxext/sphinx_nml_domain.py: https://github.com/MetOffice/jules/blob/main/doc/sphinxext/sphinx_nml_domain.py
.. _doc/sphinxext/sphinx_nml_domain.py: https://github.com/MetOffice/jules/blob/main/doc/sphinxext/sphinx_nml_domain.py

Documenting namelists
---------------------
Expand Down
59 changes: 34 additions & 25 deletions source/Reviewers/howtocommit.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ of these steps outlined below.
* `Repository Status`_ is used to coordinate ``main`` commits for all
projects.

* This operates on a first-come-first-served queing system.
* This operates on a first-come-first-served queuing system.
* To join the queue use the ``Add Item`` button.
* Do not move yourself up the queue unless agreed with others.

Expand Down Expand Up @@ -223,7 +223,7 @@ To update the test suite for an upgrade macro, please run:
Do not push the changes at this stage.

3. Test (if no KGO)
--------------------
-------------------

The amount of testing to be done at this stage depends on the complexity of the
PR, and what has already been done. A minimum level is required for even
Expand Down Expand Up @@ -324,19 +324,28 @@ are no clashes with what else has gone onto ``main``.
.. code-block:: shell

git pull
git switch <branch name>
cd <path_to>/user_guide/doc
conda activate jules-user-guide
make html
firefox build/html/index.html
git switch <branch name> # optional
cd doc

To build and check the LaTeX PDF:
# Create and activate virtual environment
python3.12 -m venv .venv
.venv/bin/pip install .
source .venv/bin/activate

# Generate html documentation in ./build/html
make clean html

# At the Met Office you can also run the following to
# deploy the documents directly into ~/public_html/jules/<branch>/
make clean deploy

To generate PDF documentation, ensure you have a LaTeX distribution
installed and run the following command. The pdf will be generated as
``./build/latex/JULES_User_Guide.pdf``:

.. code-block:: shell

make latexpdf
evince build/latex/JULES_User_Guide.pdf



4. KGO & Supporting Data (if required)
Expand Down Expand Up @@ -392,8 +401,8 @@ KGO differently*

#. The script will ask you to enter some details regarding the PR.

* Platforms: enter each platform which has a kgo change, lower case
and space seperated, e.g. `azspice ex1a`
* Platforms: enter each platform which has a KGO change, lower case
and space separated, e.g. `azspice ex1a`
* If running on the EX's it will ask for the host you ran on - this
can be found from Cylc Review.
* Path to your local clone - the script will check this exists and
Expand All @@ -419,16 +428,16 @@ KGO differently*
* This script will login as the relevant admin user as needed
* After running for a platform, the newly created variables.cylc and
shell script will be moved to Azspice
$UMDIR/kgo_update_files/<new_kgo_directory>.
``$UMDIR/kgo_update_files/<new_kgo_directory>``.
* Having run on each requested platform the new variables.cylc files
will be copied into your clone
rose-stem/site/meto/variables_<PLATFORM>.cylc.
``rose-stem/site/meto/variables_<PLATFORM>.cylc``.

.. dropdown:: Updating KGO manually (rarely needed!)

* Create a new directory for the new KGO. The naming convention is
vnXX.X_tNNNN, where NNNN is the PR number. The location of
the KGO for the nightly is $UMDIR/standard_jobs.
the KGO for the nightly is ``$UMDIR/standard_jobs``.
* Copy the new KGO from your rose-stem run into the directory
vnXX.X_tNNNN created above. Note that you need to provide a
complete set of files, not just ones which have changed answers.
Expand All @@ -437,8 +446,8 @@ KGO differently*
the previous version (i.e. move the old file to the new KGO
directory and replace it with a sym-link to the updated version)
But do not do this if the old version was a major release (vnX.X),
this is to allow intermediate kgo installs to be deleted later.
* Remember to RSync and update the bitcomparison table(see above).
this is to allow intermediate KGO installs to be deleted later.
* Remember to RSync and update the bit comparison table(see above).

.. tab-item:: JULES

Expand Down Expand Up @@ -496,10 +505,10 @@ KGO differently*
#. Verify the checksums updated properly by retriggering the failed
checksums. First retrigger ``export-source``, and then when
complete ``export-source_ex1a`` if new checksums are present there
(there is no need to retigger azspice). You may need to change the
(there is no need to retrigger azspice). You may need to change the
maximum window extent of the gui in order to see the succeeded
tasks. Now you can retrigger the failed checksums - these should
now pass if the kgo was updated in the clone correctly.
now pass if the KGO was updated in the clone correctly.

.. important::

Expand All @@ -511,14 +520,14 @@ KGO differently*
.. tip::

Between running any required testing and installing the KGO check that the
failing rose-ana tasks match those in the developers trac.log. If any have
failed for other reasons (e.g. timeout) then these should be re-triggered
before attempting to install the KGO files.
failing rose-ana tasks match those in the developers ``trac.log``. If any
have failed for other reasons (e.g. timeout) then these should be
re-triggered before attempting to install the KGO files.

4.1 Managing BIG DATA
^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^

Static input data, such as initialisations and ancilliaries, are required by
Static input data, such as initialisations and ancillaries, are required by
many tests.

.. tab-set::
Expand Down Expand Up @@ -601,7 +610,7 @@ If the requirement is to update existing files, then further care is required.
---------

Once testing has passed on the local Met Office machines then ensure all
changes for macros and kgos have been committed to the local copy of the
changes for macros and KGOs have been committed to the local copy of the
branch and then push the changes back to the remote branch.

.. tip::
Expand Down
Loading