MetOffice · Yaswant Pradhan (yaswant) · Sep 13, 2024 · Sep 16, 2024 · Sep 16, 2024 · Jul 21, 2025
diff --git a/.github/workflows/publish_wps.yml b/.github/workflows/publish_wps.yml
@@ -20,18 +20,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' }}

diff --git a/.github/workflows/requirements.txt b/.github/workflows/requirements.txt
@@ -1,4 +1,7 @@
-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
+
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,9 @@
-#build output
-/build/
+build/
+*.egg-info/
+.idea
+.venv/
+venv/
+uv.lock
 
-#IDE files
-/.idea
-/.venv/
-/venv/
+__pycache__/
+*.py[cod]
diff --git a/README.md b/README.md
@@ -1,19 +1,133 @@
 # Simulation Systems
 
-This repository contains documentation that is common across the many simulation and modelling codes owned by the Met Office.
+This repository contains documentation that is common across the many simulation
+and modelling codes owned by the Met Office.
 
-To build this documentation from the top level of the project run:
+```mermaid
+---
+config:
+  theme: neutral
+---
+flowchart
+
+subgraph ss["Simulation Systems Repositories<br>--"]
+direction TB
+  subgraph Other[**Other**]
+  direction TB
+    moci@{shape: rect, label: MOCI}
+    monc@{shape: rect, label: MONC}
+  end
+  subgraph Common[**Common**]
+  direction TB
+    jules
+    ukca
+    casim
+    socrates
+    shumlib
+  end
+  subgraph UM[**Unified Model**]
+  direction TB
+    um@{shape: rect, label: um}
+    gcom[gcom]
+    aux@{shape: bow-rect , label: um_aux}
+    meta@{shape: procs, label: um_meta}
+    mule[mule]
+    doc@{shape: doc, label: um_doc}
+  end
+  subgraph Momentum[**Momentum&reg;**]
+  direction TB
+    apps[lfric_apps]
+    core[lfric_core]
+    rose_picker
+  end
+end
+%% Style
+style ss font-size:1.3em
+style Momentum fill: #abfaabff
+style Common fill: #aee3f8ff
+style UM fill: #facdcdff
+style mule fill: #1de01da9
+style shumlib fill: #1de01da9
+style rose_picker fill: #1de01da9
+style apps fill: #1de01da9
+style core fill: #1de01da9
+style casim fill: #1de01da9
+style ukca fill: #1de01da9
+style socrates fill: #1de01da9
+style moci fill: #1de01da9
+style monc fill: #1de01da9
+style um fill: #f7351b9f
+style gcom fill: #f7351b9f
+style aux fill: #f7351b9f
+style meta fill: #f7351b9f
+style doc fill: #f7351b9f
+style jules fill: #cfcf62ff
+%% Links
+click jules "https://github.com/MetOffice/jules"
+click ukca "https://github.com/MetOffice/ukca"
+click casim "https://github.com/MetOffice/casim"
+click moci "https://github.com/MetOffice/moci"
+click monc "https://github.com/MetOffice/monc"
+click socrates "https://github.com/MetOffice/socrates"
+click shumlib "https://github.com/MetOffice/shumlib"
+click um "https://github.com/MetOffice/um"
+click gcom "https://github.com/MetOffice/gcom"
+click aux "https://github.com/MetOffice/um_aux"
+click meta "https://github.com/MetOffice/um_meta"
+click doc "https://github.com/MetOffice/um_doc"
+click mule "https://github.com/MetOffice/mule"
+click apps "https://github.com/MetOffice/lfric_apps"
+click core "https://github.com/MetOffice/lfric_core"
+click rose_picker "https://github.com/MetOffice/rose_picker"
+
+%% Dependencies
+Momentum ==> Common
+UM ==> Common
+um ==> gcom & aux & meta & mule
+apps ==> core ==> rose_picker
 ```
-conda env create -f env.yml
-conda activate sphinx_doc_env
-make clean html
+
+Expected visibility by late 2025 - early 2026:
+$\textsf{\color{#1de01d}public (Open Source) \color{#f7351b}private (Closed Source) \color{#cfcf62}public (TBC)}$
+
+<!-- <code style="background:#1de01da9">public (Open Source)</code> <code style="background:#f7351b9f">private (Closed Source)</code> <code style="background:#cfcf62ff">public (TBC)</code> -->
+
+## Building the documentation
+
+A quick and clean way to get the package dependencies is via
+[uv](https://docs.astral.sh/uv/) package manager.
+
+```sh
+git clone https://github.com/MetOffice/simulation-systems
+cd simulation-systems
+
+# Install dependencies (see pyproject.toml) in project .venv
+uv sync
+uv run make clean html
+
+# Verify documentation
 firefox build/html/index.html
 ```
 
-The documentation is written in sphinx markup. To develop changes to this 
+Alternatively, if your have Python-3.11 or higher installed (sphinx==8.2.3
+requirement), you can install the dependencies in a virtual environment via
+`pip`, and build the documentation like:
+
+```sh
+cd simulation-systems
+
+</path/to/python3.11+> -m venv .venv
+source .venv/bin/activate
+pip install .
+make clean html
+```
+
+## Contributing to the documentation
+
+The documentation is written in sphinx markup. To develop changes to this
 documentation first create an issue detailing the changes that are required.
 Then create a branch in a clone of this repository, linking it to your issue and
-regularly building your changes as described above. 
+regularly building your changes as described above.
 
-Once happy with your development create a pull request and request a review
-from MetOffice/ssdteam. 
+Once happy with your development create a pull request and request a review from
+[MetOffice/ssdteam](https://github.com/orgs/MetOffice/teams/ssdteam).
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,14 @@
+[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",
+]
diff --git a/source/FurtherDetails/code_of_conduct.rst b/source/FurtherDetails/code_of_conduct.rst
@@ -10,4 +10,4 @@ of Met Office Simulation Systems.
 2. Be tolerant of others but do not abuse the tolerance of others.
 3. Respond to others constructively and in a reasonable time frame.
 4. Communicate inclusively and contribute to the community.
-5. Focus on outcomes, not processes.
+5. Focus on outcomes, not processes.
diff --git a/source/FurtherDetails/dos_donts.rst b/source/FurtherDetails/dos_donts.rst
@@ -2,52 +2,61 @@
 
 Do's and Don'ts
 ===============
+
 Please Do
 ---------
+
 **Consult** Code Owners and system team. This will help maintain awareness and
 mitigate problems early on. This is the most common root cause of problems,
 sometimes years later.
 
 **Plan** your work aimed at the trunk across single or multiple tickets:
+
     * Ensure tickets are not too big or small.
-    * Coherent parts of the overall change are contained in a single ticket
-    * Consider using an overarching ticket to link everything together
+    * Coherent parts of the overall change are contained in a single ticket.
+    * Consider using an overarching ticket to link everything together.
 
-**Document your work** using tickets, TRAC pages, :ref:`formal documentation <docs>`
-and code comments. These help others and your future-self understand your work.
+**Document your work** using tickets, TRAC pages, :ref:`formal documentation
+<docs>` and code comments. These help others and your future-self understand
+your work.
 
-**Meaningful names** for tickets, branches and variables. These help others and
-your future-self understand your work. "My_Branch", "Fix" are not helpful.
+**Use meaningful names** for tickets, branches and variables. These help others
+and your future-self understand your work. "My_Branch", "Fix" are not helpful.
 
-**Be considerate** of other users/developers. Their skill-sets and working days may be very different to yours. All changes are visible to all users worldwide.
+**Be considerate** of other users/developers. Their skill-sets and working days
+may be very different to yours. All changes are visible to all users worldwide.
 
-**Keep the ticket status up to date.** This enables the Simulation Systems
-and Deployment Team to monitor the progress of your ticket and potential conflicts.
+**Keep the ticket status up to date.** This enables the Simulation Systems and
+Deployment Team to monitor the progress of your ticket and potential conflicts.
 
-**Link to tickets in other MOSRS repositories**, eg jules:#1, ukca:#72
+**Link to tickets in other MOSRS repositories**, e.g., ``jules:#1``,
+``ukca:#72``.
 
 Please Do Not
 -------------
 
-**Do not use svn commands.** Please use `FCM <http://metomi.github.io/fcm/doc/user_guide/>`_ for all development work.
+**Do not use svn commands.** Please use `FCM <http://metomi.github.io/fcm/doc/
+user_guide/>`_ for all development work.
 
-**Do not merge the trunk into your branch** for UM, JULES, UKCA and LFRic Apps changes as this breaks many aspects of how
-TRAC and fcm work. This will cause diffs to display incorrectly and causes
-database problems when merging. Instead, please create a head of trunk branch
-and merge in your old branch.
+**Do not merge the trunk into your branch** for UM, JULES, UKCA and LFRic Apps
+changes as this breaks many aspects of how TRAC and FCM work. This will cause
+diffs to display incorrectly and causes database problems when merging.
+Instead, please create a head of trunk branch and merge in your old branch.
 
 **Do not develop using head of trunk branching if not needed.** Many aspects of
 the UM, JULES and UKCA workflows rely on version branching.
 
 **Licensing** - Don't add code to any project (or to any branch thereof) that
 has been developed under a different license without agreement from the
 Simulation Systems and Deployment Team. This includes lifting Fortran code or
-text from books. Our repositiories must not infringe copyright.
+text from books. Our repositories must not infringe copyright.
 
-**Add or link to old code** or tickets that predate MOSRS, for example...
+**Add or link to old code** or tickets that predate MOSRS, for example:
 
-* Link to tickets in old internal repositories- links will either not resolve or be incorrect
-* Add a version of the UM code older than UM 9.2 as a branch to the UM repository
+    * Link to tickets in old internal repositories; links will either not
+      resolve or be incorrect.
+    * Add a version of the UM code older than UM 9.2 as a branch to the UM
+      repository.
 
 **Request support by raising a ticket**. Newly raised tickets are not monitored.
-Use the appropriate :ref:`support` channels.
+Use the appropriate :ref:`support` channels.
diff --git a/source/FurtherDetails/glossary.rst b/source/FurtherDetails/glossary.rst
@@ -41,10 +41,10 @@ Further Commit:
     way.
 
 Known Good Output (KGO):
-    In order to verify that the model output hasn't been modified by a set of changes
-    the test suite contains a stored set of output as a reference. This is known
-    as the KGO and changes that alter this require special treatment. For more
-    information see :ref:`kgo`.
+    In order to verify that the model output hasn't been modified by a set of
+    changes the test suite contains a stored set of output as a reference. This
+    is known as the KGO and changes that alter this require special treatment.
+    For more information see :ref:`kgo`.
 
 Head of Trunk:
     The most recent code revision on the trunk. Branches are taken from here
@@ -83,4 +83,4 @@ Version:
     Each release of the codebase is completed by tagging the latest revision of
     the trunk with a version number. This version should be used for creating
     code branches from and will also be used by the parallel suite teams as a
-    starting point for creating the next operational suite.
+    starting point for creating the next operational suite.
diff --git a/source/FurtherDetails/index.rst b/source/FurtherDetails/index.rst
@@ -12,4 +12,5 @@ Further Details
     glossary
     code_of_conduct
     dos_donts
-    change_notes
+    change_notes
+
diff --git a/source/FurtherDetails/support.rst b/source/FurtherDetails/support.rst
@@ -26,12 +26,13 @@ If you still require assistance, then contact the appropriate support team.
 Please respect the clear demarcations between the scope for different teams.
 
 Core Capability Development Team (formally LFRic Team):
-   * Support windows for LFRic releases TBC
+* Support windows for LFRic releases TBC
 
-Simulation Systems and Deployment Team (formerly UM System Team and CRUM team) supports:
-   * UM, Shumlib and JULES versions released in the last 12 months,
-   * main version used in the Met Office Operational Suite.
-   * specific climate configurations .. todo - details of which configs
+Simulation Systems and Deployment Team (formerly UM System Team and CRUM team)
+supports:
+* UM, Shumlib and JULES versions released in the last 12 months,
+* main version used in the Met Office Operational Suite.
+* specific climate configurations .. todo - details of which configs
 
 
 Escalation