Local deploy config (MetOffice#530)

Author: yaswant

Makefile

@@ -8,6 +8,11 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 
+# For local deployment to ~/public_html/<repo>/<branch>
+REPO := $(notdir $(shell git rev-parse --show-toplevel))
+BRANCH := $(shell git rev-parse --abbrev-ref HEAD)
+DEPLOYDIR  = $(HOME)/public_html
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -17,4 +22,7 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+deploy:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(DEPLOYDIR)/$(REPO)/$(BRANCH)" $(SPHINXOPTS) $(O)

README.md

@@ -1,61 +1,93 @@
 # Simulation Systems
 
-This repository contains documentation that is common across the many
+[![Docs](https://github.com/MetOffice/simulation-systems/actions/workflows/publish_wps.yaml/badge.svg)](https://github.com/MetOffice/simulation-systems/actions/workflows/publish_wps.yaml)
+
+This repository contains the working practices documentation common to the
+various
 [simulation and modelling repositories](https://github.com/MetOffice/simulation-systems/wiki)
 owned by the Met Office.
 
-## Build the documentation
+The documentation in the repository can be compiled in different ways.
 
-A quick and clean way to get the package dependencies is via
-[uv](https://docs.astral.sh/uv/) package manager.
+> [!NOTE]
+> Optional system dependencies for PDF generation may require LaTeX
+> distributions and other third-party libraries.
 
-Ps: Optional system dependencies for PDF generation may require LaTeX
-distributions and other third-party libraries.
+## Setup environment
 
-### using uv
+You can set up the environment ro build and deploy the documentation using any
+of the following methods:
+
+### 1. Using uv
+
+A quick and clean way to get the package dependencies is via the
+[uv](https://docs.astral.sh/uv/) package manager.
 
 ```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
+### 2. 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:
+If you have Python 3.11 or higher installed (`sphinx==8.2.3` required), you can
+use pip:
 
 ```shell
+git clone https://github.com/MetOffice/simulation-systems
 cd simulation-systems
 
-</path/to/python3.11+> -m venv .venv
+<path/to/python3.11+> -m venv .venv
 source .venv/bin/activate
 pip install .
-make clean html
 ```
 
-### using conda
+### 3. Using conda
 
 ```shell
+git clone https://github.com/MetOffice/simulation-systems
+cd simulation-systems
+
 conda env create -f env.yml
 conda activate sphinx_doc_env
+```
+
+## Build documentation
+
+```shell
+# For uv environment
+uv run make clean html
+
+# For pip or conda environments
 make clean html
-firefox build/html/index.html
+```
+
+After building, the HTML documentation can be found in the `build/html/`
+directory of your local repository. You can open the documentation in any web
+browser.
+
+**Met Office users** can skip build step above and deploy the documentation
+directly to a predefined location:
+`~/public_html/simulation-systems/<branch-name>/html/`
+
+```shell
+uv run make clean deploy  # uv env
+# OR
+make clean deploy  # pip or conda env
 ```
 
 ## 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.
+Please follow the project's [Code of Conduct](CONTRIBUTING.md)
+
+The documentation is written in Sphinx markup. To propose changes:
+
+1. Create an issue detailing the required changes.
+2. Create a branch in your clone of this repository, linking it to your issue.
+3. Regularly build your changes as described above.
 
-Once happy with your development create a pull request and request a review from
+Once satisfied, create a pull request and request a review from
 [MetOffice/ssdteam](https://github.com/orgs/MetOffice/teams/ssdteam).

env.yml

@@ -1,6 +1,6 @@
 name: sphinx_doc_env
 dependencies:
-  - python>=3
+  - python>=3.11
   - pip
   - pip:
     - -r .github/workflows/requirements.txt

source/conf.py

@@ -19,9 +19,9 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Simulation Systems'
-copyright = 'Met Office'
-author = 'Simulation Systems and Deployment Team'
+project = "Simulation Systems"
+copyright = "Met Office"
+author = "Simulation Systems and Deployment Team"
 
 
 # -- General configuration ---------------------------------------------------
@@ -34,14 +34,14 @@
 
 # Added to use dropdowns with command: pip install sphinx-design
 extensions = [
-    'sphinx_design',
-    'sphinx_copybutton',
-    'sphinxcontrib.rsvgconverter',
-    'sphinxcontrib.mermaid',
+    "sphinx_design",
+    "sphinx_copybutton",
+    "sphinxcontrib.rsvgconverter",
+    "sphinxcontrib.mermaid",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -55,7 +55,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 
 html_theme_options = {
     "footer_start": ["crown-copyright"],
@@ -93,6 +93,6 @@
 # -- Options for linkcheck builder -------------------------------------------
 linkcheck_anchors = False
 linkcheck_ignore = [
-    r'.*\.py$',  # Ignores URLs ending with .py
-    r'https://github.com/MetOffice/um*',
+    r".*\.py$",  # Ignores URLs ending with .py
+    r"https://github.com/MetOffice/um*",
 ]