Rewrite all working practices for git and GitHub (#497)

Co-authored-by: James Bruten <109733895+james-bruten-mo@users.noreply.github.com>
Co-authored-by: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com>

Author: 3 people

.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/

README.md

@@ -1,19 +1,61 @@
 # 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 repositories](https://github.com/MetOffice/simulation-systems/wiki)
+owned by the Met Office.
 
-To build this documentation from the top level of the project run:
+## Build the documentation
+
+A quick and clean way to get the package dependencies is via
+[uv](https://docs.astral.sh/uv/) package manager.
+
+Ps: Optional system dependencies for PDF generation may require LaTeX
+distributions and other third-party libraries.
+
+### using uv
+
+```shell
+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
+```
+
+### using pip
+
+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:
+
+```shell
+cd simulation-systems
+
+</path/to/python3.11+> -m venv .venv
+source .venv/bin/activate
+pip install .
+make clean html
 ```
+
+### using conda
+
+```shell
 conda env create -f env.yml
 conda activate sphinx_doc_env
 make clean html
 firefox build/html/index.html
 ```
 
-The documentation is written in sphinx markup. To develop changes to this 
+## Contributing
+
+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).

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",
+]