From a7f46e73aea3206a5b6c1198696061e7c74dd508 Mon Sep 17 00:00:00 2001 From: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> Date: Wed, 1 Apr 2026 13:26:47 +0100 Subject: [PATCH] Update jules doc section and fix typos --- source/Development/jules_docs.rst | 6 ++-- source/Reviewers/howtocommit.rst | 59 ++++++++++++++++++------------- 2 files changed, 37 insertions(+), 28 deletions(-) diff --git a/source/Development/jules_docs.rst b/source/Development/jules_docs.rst index 21186dba..34e529bb 100644 --- a/source/Development/jules_docs.rst +++ b/source/Development/jules_docs.rst @@ -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 --------------------- diff --git a/source/Reviewers/howtocommit.rst b/source/Reviewers/howtocommit.rst index d0a5e0a6..659c3f10 100644 --- a/source/Reviewers/howtocommit.rst +++ b/source/Reviewers/howtocommit.rst @@ -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. @@ -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 @@ -324,19 +324,28 @@ are no clashes with what else has gone onto ``main``. .. code-block:: shell git pull - git switch - cd /user_guide/doc - conda activate jules-user-guide - make html - firefox build/html/index.html + git switch # 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// + 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) @@ -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 @@ -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/. + ``$UMDIR/kgo_update_files/``. * Having run on each requested platform the new variables.cylc files will be copied into your clone - rose-stem/site/meto/variables_.cylc. + ``rose-stem/site/meto/variables_.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. @@ -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 @@ -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:: @@ -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:: @@ -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::