Sanitise docs 2 (#427)

Author: yaswant

.github/workflows/publish_wps.yml

@@ -4,8 +4,9 @@ on:
   push:
     branches:
     - main
+    - github_wps
   pull_request:
-    types: [opened,reopened,review_requested]
+    types: [opened, reopened, synchronize]
   workflow_dispatch:
 
 permissions:
@@ -20,18 +21,23 @@ jobs:
       run: |
         git config --global user.email "umsysteam@metoffice.gov.uk"
         git config --global user.name "SSD Developers"
+
     - name: Check out source
       uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
+
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v6
       with:
-        python-version: '3.x'
+        python-version: '3.12'
+
     - name: Install Dependencies
-      run: |
-        pip install -r .github/workflows/requirements.txt
+      run: uv sync
 
-    - name: build docs
-      run: |
-        make clean html
+    - name: Lint Docs
+      run: uv run sphinx-lint source
+
+    - name: Build Docs
+      run: uv run make clean html
 
     - name: commit docs to gh-pages branch
       if: ${{ github.event_name == 'push' && github.ref_name == 'main' }}

.github/workflows/requirements.txt

@@ -1,4 +1,8 @@
-Sphinx==6.2.1
-sphinx-design==0.5.0
-pydata-sphinx-theme
-sphinx-sitemap
+sphinx==8.2.3
+pydata-sphinx-theme==0.16.1
+sphinx-design==0.6.1
+sphinx-copybutton==0.5.2
+sphinx-lint==1.0.0
+sphinx-sitemap==2.8.0
+sphinxcontrib-svg2pdfconverter==1.3.0
+

.gitignore

@@ -1,7 +1,8 @@
-#build output
-/build/
-
-#IDE files
-/.idea
-/.venv/
-/venv/
+*.egg-info/
+*.py[cod]
+.idea
+.venv/
+__pycache__/
+build/
+uv.lock
+venv/

pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "simulation-systems"
+version = "0.1.0"
+description = "Simulation Systems Working Practices"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydata-sphinx-theme==0.16.1",
+    "sphinx==8.2.3",
+    "sphinx-design==0.6.1",
+    "sphinx-copybutton==0.5.2",
+    "sphinx-lint==1.0.0",
+    "sphinx-sitemap==2.8.0",
+    "sphinxcontrib-svg2pdfconverter==1.3.0",
+]

source/Development/Diagnostics/lfric_diagnostics.rst

@@ -2,46 +2,60 @@
 
 STASH [#f1]_
 ============
-Information on every diagnostic available to the
-model is stored in a single file named ``STASHmaster_A``, which is read into
-the model at the start of the run.
 
-The UM's ``STASHmaster_A`` and associated help text file ``STASHmaster-meta.conf``
-are available in your branch at
+Information on every diagnostic available to the model is stored in a single
+file named ``STASHmaster_A``, which is read into the model at the start of the
+run.
+
+The UM's ``STASHmaster_A`` and associated help text file
+``STASHmaster-meta.conf`` are available in your branch at
 ``vnXX.Y_<branch_name>/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/``.
 
 .. note::
-  When running the UM rose stem suite, the suite will automatically use the
-  ``STASHmaster_A file`` from your branch when testing your code.
+
+    When running the UM rose stem suite, the suite will automatically use the
+    ``STASHmaster_A file`` from your branch when testing your code.
 
 The following principles apply when altering the STASHmaster:
 
 ..
   JW suggest need to include STASH entry guidance here. Maybe an issue for this would be useful?
 
-* If you add a new diagnostic to the ``STASHmaster_A`` file then you **must** also add to the stash master help text in :ref:`stashmaster-meta`.
-* If you are altering the stashmaster, this may be referred to the FFPP governance board by the sci/tech or code reviewers - see the STASH entry guidelines.
-* If your change has new stash items or changed/added attributes as an option code, versions mask etc., then first you have to get them reserved and recorded (published) on the reservation web page STASH/ReservedCodes 
-* Note that every reservation should be linked to a ticket with the correct explanation and a milestone. This rule applies to all stash related tables placed on this page.
-* Although reservations could be some kind of self-service, contact the section owner first nevertheless. This could help to organise new items (when possible) in some logical groups.
+* If you add a new diagnostic to the ``STASHmaster_A`` file then you **must**
+  also add to the stash master help text in :ref:`stashmaster-meta`.
+* If you are altering the stashmaster, this may be referred to the FFPP
+  governance board by the sci/tech or code reviewers - see the STASH entry
+  guidelines.
+* If your change has new stash items or changed/added attributes as an option
+  code, versions mask etc., then first you have to get them reserved and
+  recorded (published) on the reservation web page STASH/ReservedCodes
+* Note that every reservation should be linked to a ticket with the correct
+  explanation and a milestone. This rule applies to all stash related tables
+  placed on this page.
+* Although reservations could be some kind of self-service, contact the section
+  owner first nevertheless. This could help to organise new items
+  (when possible) in some logical groups.
 * For new option code numbers contact the STASH code owner.
 
 .. note::
-  Complete details of the STASH system (including the syntax used in the
-  ``STASHmaster_A`` file) can be found in
-  `UMDP C04 <https://code.metoffice.gov.uk/doc/um/latest/papers/umdp_C04.pdf>`_
+
+    Complete details of the STASH system (including the syntax used in the
+    ``STASHmaster_A`` file) can be found in `UMDP C04
+    <https://code.metoffice.gov.uk/doc/um/latest/papers/umdp_C04.pdf>`__
 
 .. _stashmaster-meta:
 
 STASHmaster-meta.conf
 ---------------------
-If you are adding a new UM STASH diagnostic you must also add help text to the STASHmaster-meta.conf.
-This will provide others with help on your diagnostic. You will need to identify the stash entry with
-a ``[stashmaster:code(xyz)]`` section header, where the xyz is the stash code in the form
-``section number * 1000 + item number``.
 
-Include a full name, any units and explanatory text. You should also add a description field that matches
-the full name of the diagnostic. For example:
+If you are adding a new UM STASH diagnostic you must also add help text to the
+STASHmaster-meta.conf. This will provide others with help on your diagnostic.
+You will need to identify the stash entry with a ``[stashmaster:code
+(xyz)]`` section header, where the xyz is the stash code in the form ``section
+number * 1000 + item number``.
+
+Include a full name, any units and explanatory text. You should also add a
+description field that matches the full name of the diagnostic. For example:
 
 .. code-block::
 
@@ -56,7 +70,8 @@ the full name of the diagnostic. For example:
         =number of moles of NO2 removed by this process per second in the
         =whole model.
 
-This assists the model user in being able to find useful help text on their diagnostic.
+This assists the model user in being able to find useful help text on their
+diagnostic.
 
 
 .. rubric:: Footnotes

source/Development/Diagnostics/um_stashmaster.rst

@@ -9,8 +9,8 @@ JULES testing is run with the following command from a working copy:
 
 -----
 
-The JULES rose stem testing includes a range of builds using a variety of compilers,
-several configurations, and rose-ana tasks to check the output.
+The JULES rose stem testing includes a range of builds using a variety of
+compilers, several configurations, and rose-ana tasks to check the output.
 
 The output is checked for correctness both by comparing the output to a set of
 stored :ref:`KGO files <kgo>`.
@@ -21,20 +21,20 @@ stored :ref:`KGO files <kgo>`.
     :ref:`jules-shared<shared-namelists>` metadata then these changes
     will need to be tested :ref:`with the UM<um_testing>` and
     :ref:`with LFRic Apps<lfric_apps_test>`. If you have access to LFRic, the
-    :ref:`traclog` will state whether LFRic testing is required based on the branch
-    diff. If you do not have LFRic access, this testing will need to be completed by
-    your Met Office contact.
+    :ref:`traclog` will state whether LFRic testing is required based on the
+    branch diff. If you do not have LFRic access, this testing will need to
+    be completed by your Met Office contact.
 
     See :ref:`multirepo` for details on how to carry out this testing.
 
     .. important::
-      For **jules-shared** changes, when LFRic testing, the changes
-      need to be manually synced to the LFRic location. When UM
-      testing, this is not required as **jules-shared** is imported
-      from the JULES branch.
+        For **jules-shared** changes, when LFRic testing, the
+        changes need to be manually synced to the LFRic location. When UM
+        testing, this is not required as **jules-shared** is imported from the
+        JULES branch.
 
-Below is a (by no means comprehensive) set of groups that you may wish to use on
-Met Office systems.
+Below is a (by no means comprehensive) set of groups that you may wish to use
+on Met Office systems.
 
 +--------------------+----------------------------------------------------------+
 | Group              | Description                                              |

source/Development/TestSuites/jules.rst

@@ -4,50 +4,59 @@ Testing LFRic Apps
 ==================
 
 Rose stem:
+
     LFRic Apps testing uses rose-stem and is run with the following commands
     from a working copy:
 
-    .. code-block::
+    .. code-block:: shell
 
         export CYLC_VERSION=8
         rose stem --group=developer
         cylc play <working copy name>
         cylc gui
 
 Local testing:
+
     Alternatively, a single application can be built and run locally using
-    `these instructions <https://code.metoffice.gov.uk/trac/lfric_apps/wiki/local_builds>`_
+    `these instructions
+    <https://code.metoffice.gov.uk/trac/lfric_apps/wiki/local_builds>`__
 
-    This test does not use rose or cylc and is particularly useful for
-    checking for compile errors while developing.
+    This test does not use rose or cylc and is particularly useful for checking
+    for compile errors while developing.
 
 -----
 
 .. important::
 
-    When specifying the lfric_core source the lfric_core revision **must** be updated in ``dependencies.sh``.
+    When specifying the lfric_core source the lfric_core revision **must** be
+    updated in ``dependencies.sh``.
 
-    * If setting the source to an fcm URL, the mirror (``.xm_``) needs to be used and the revision can either be blank (for latest commit) or any valid revision for that branch.
-    * If setting the source to a Working Copy, the hostname needs to be provided (as Hostname:Path) and the revision must be blank.
+    * If setting the source to an fcm URL, the mirror (``.xm_``) needs to be
+      used and the revision can either be blank (for latest commit) or any
+      valid revision for that branch.
+    * If setting the source to a Working Copy, the hostname needs to be
+      provided (as Hostname:Path) and the revision must be blank.
 
     For more details, see :ref:`multi-repo_testing`.
 
 
 Rose stem
 ---------
-The LFRic Apps rose stem includes a range of tests to exercise all the applications
-stored in this repository, using multiple compilers, and checksum and plot tasks to
-confirm the outputs.
+
+The LFRic Apps rose stem includes a range of tests to exercise all the
+applications stored in this repository, using multiple compilers, and checksum
+and plot tasks to confirm the outputs.
 
 .. tip::
 
-    For LFRic Apps it is possible to update the checksum files on your branch as
-    you progress your development to aid with testing. Details on how to do this
-    are on the :ref:`KGO page <kgo>`.
+    For LFRic Apps it is possible to update the checksum files on your branch
+    as you progress your development to aid with testing. Details on how to do
+    this are on the :ref:`KGO page <kgo>`.
 
-Below is a (by no means comprehensive) set of groups that you may wish to use on
-Met Office systems. Note that there is a lot of overlap between these groups,
-and that you can specify more than one at once, e.g. ``--group=developer,gungho_model``.
+Below is a (by no means comprehensive) set of groups that you may wish to use
+on Met Office systems. Note that there is a lot of overlap between these
+groups, and that you can specify more than one at once, e.g.
+``--group=developer,gungho_model``.
 
 +--------------------+----------------------------------------------------------+
 | Group              | Description                                              |
@@ -76,8 +85,8 @@ and that you can specify more than one at once, e.g. ``--group=developer,gungho_
 +--------------------+----------------------------------------------------------+
 
 As well as these general groups, each area in ``<lfric_apps>/applications`` and
-``<lfric_apps>/science`` have a set of specific groups that are structured as below,
-with ``name`` matching the directory name of the area.
+``<lfric_apps>/science`` have a set of specific groups that are structured as
+below, with ``name`` matching the directory name of the area.
 
 +--------------------+----------------------------------------------------------+
 | Group              | Description                                              |

source/Development/TestSuites/lfric_apps.rst

@@ -5,11 +5,14 @@ Testing LFRic Core
 
 .. note::
 
-    At the LFRic Apps vn2.0 release, the cylc7 LFRic Core suite was deprecated and the make test-suite functionality removed. Only the cylc8 suite is now maintained.
+    At the LFRic Apps vn2.0 release, the cylc7 LFRic Core suite was deprecated
+    and the make test-suite functionality removed. Only the cylc8 suite is now
+    maintained.
 
-LFRic testing is launched with Cylc8 rose-stem commands (as in eg. LFRic Apps):
+LFRic testing is launched with Cylc8 rose-stem commands (as in eg. LFRic
+Apps):
 
-.. code-block::
+.. code-block:: shell
 
     export CYLC_VERSION=8
     rose stem --group=developer
@@ -22,14 +25,19 @@ that the system level developer tests pass on all the applications. These are
 launched from make and utilise rose and cylc.
 
 While developing your change, for expediency you may want to run the tests for
-only some applications. This can be done by changing the group you run, eg ``--group=simple_diffusion``.
+only some applications. This can be done by changing the group you run, eg
+``--group=simple_diffusion``.
 
-The command above will launch the developer suite. You can include slightly more testing if required by running ``--group=all`` instead (this includes the developer suite).
+The command above will launch the developer suite. You can include slightly
+more testing if required by running ``--group=all`` instead (this includes the
+developer suite).
 
-It is also possible to run on a single platform, eg. ``--group=ex1a``. To select which meto EX machine is used, add ``-S USE_EX<AB/CD/Z>``.
+It is also possible to run on a single platform, eg. ``--group=ex1a``. To
+select which meto EX machine is used, add ``-S USE_EX<AB/CD/Z>``.
 
 .. tip::
 
     For more details on LFRic testing including details of unit tests please
-    visit the `LFRic testing trac wiki page <https://code.metoffice.gov.uk/trac/lfric/wiki/LFRicTechnical/Testing>`_.
+    visit the `LFRic testing trac wiki page
+    <https://code.metoffice.gov.uk/trac/lfric/wiki/LFRicTechnical/Testing>`__.