Refactor Sphinx documentation build workflow and update requirements file

.github/workflows/build-sphinx-docs.yaml

@@ -8,79 +8,85 @@ name: Build Sphinx Docs
 
 on:
   workflow_call:
-
-  inputs:
-   # The inputs are the parameters that can be passed
-   # to this resuable workflow by the calling workflow.
-   docs-directory:
-      description: 'Directory containing the documentation to build'
-      required: false
-      type: string
-      default: './documentation'
-
-   requirements:
-      description: 'The path to the requirements file to install dependencies from'
-      required: false
-      type: string
-      default: '.github/dependencies/build-sphinx-docs/requirements.txt'
+    inputs:
+      docs-directory:
+        description: 'Directory containing the documentation to build'
+        required: false
+        type: string
+        default: './documentation'
+      requirements:
+        description: 'Path to the requirements file to install dependencies from'
+        required: true
+        type: string
+        default: 'requirements.txt'
+      sphinx-opts:
+        description: 'Additional options to pass to the Sphinx build command'
+        required: false
+        type: string
+        default: '-W --keep-going -n'
+      build-directory:
+        description: 'Directory to output the html documentation to'
+        required: false
+        type: string
+        default: '${{inputs.docs-directory}}/build'
+      runner:
+        description: 'The runner to use for the job'
+        required: false
+        type: string
+        default: 'ubuntu-latest'
+      timeout:
+        description: 'Timeout for the job in minutes'
+        required: false
+        type: number
+        default: 5
 
 jobs:
-
   build-sphinx-docs:
-     name: build sphinx docs
-     runs-on: ubuntu-24.04
-     steps:
+    name: Build Sphinx Docs
+    runs-on: ${{ inputs.runner }}
+    env:
+      DOCS_DIR: ${{ inputs.docs-directory }}
+      REQS_FILE: ${{ inputs.requirements }}
+      SPHINX_OPTS: ${{ inputs.sphinx-opts }}
+      BUILD_DIR: ${{ inputs.build-directory }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
 
-       # Repository checkout and python environment setup
-        - id: extract
-          name: Extract repo
-          uses: actions/checkout@v4
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles(env.REQS_FILE) }}
+          restore-keys: ${{ runner.os }}-pip-
 
-        - id: setup_environment
-          name: Setup Python environment
-          uses: actions/setup-python@v5
-          with:
-            python-version: '3.12'
+      - name: Minimize pip cache
+        run: python3 -m pip cache purge || true
 
-        # The caching step speeds up subsequent runs by caching
-        # previously installed packages. It generates a new cache
-        # only if the requirements file has changed.
-        - id: caching
-          name: Cache pip
-          uses: actions/cache@v4
-          with:
-            path: ~/.cache/pip
-            key: ${{ runner.os }}-pip-${{ hashFiles(${{ inputs.requirements }}) }}
-            restore-keys: |
-              ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r "$REQS_FILE"
 
-        # The installation of dependencies is then done by
-        # upgrading pip and installing the packages from
-        # the requirements file.
-        - id: dependencies
-          name: Install Python packages
-          run: |
-            python3 -m pip install --upgrade pip && \
-            python3 -m pip install -r ${{ inputs.requirements }}
+      - name: Lint Sphinx docs
+        working-directory: ${{ env.DOCS_DIR }}
+        run: sphinx-lint .
 
-        - id: sphinx_build
-          name: Build sphinx HTML docs
-          working-directory: ${{ inputs.docs-directory }}
-          run: make html SPHINXOPTS="-W --keep-going -n"
+      - name: Build Sphinx HTML docs
+        working-directory: ${{ env.DOCS_DIR }}
+        run: |
+          make html SPHINXOPTS="$SPHINX_OPTS" BUILDDIR="$BUILD_DIR"
 
-        # Permissions are set to allow GitHub Pages to access the built files
-        - id: permissions
-          name: Set permissions
-          run: chmod -c -R +rX "${{ inputs.docs-directory }}/build/html"
 
-        # The artifact containing the built HTML files is uploaded
-        # to GitHub Pages only when the workflow is triggered by a push
-        # or a merge group event on the main branch.
-        - id: upload_artifact
-          name: Upload artifact
-          if: ${{ (github.event_name == 'push' || github.event_name == 'merge_group') && github.ref_name == 'main'}}
-          uses: actions/upload-pages-artifact@v3
-          with:
-             name: github-pages
-             path: ${{ inputs.docs-directory }}/build/html
-             retention-days: 1
+      - name: Upload artifact to GitHub Pages
+        if: ${{ (github.event_name == 'push' || github.event_name == 'merge_group') && github.ref_name == 'main'}}
+        uses: actions/upload-pages-artifact@v4
+        with:
+          name: github-pages
+          path: "$BUILD_DIR/html"
+          retention-days: 1

.github/workflows/deploy-sphinx-docs.yaml

@@ -0,0 +1,37 @@
+# ------------------------------------------------------------------------------
+#  (c) Crown copyright Met Office. All rights reserved.
+#  The file LICENCE, distributed with this code, contains details of the terms
+#  under which the code may be used.
+# ------------------------------------------------------------------------------
+
+name: Deploy Sphinx Docs
+
+on:
+  workflow_call:
+    inputs:
+      runner:
+        description: 'The runner to use for the job'
+        required: false
+        type: string
+        default: 'ubuntu-latest'
+      timeout:
+        description: 'Timeout for the job in minutes'
+        required: false
+        type: number
+        default: 5
+jobs:
+  deploy-sphinx-docs:
+    runs-on: ${{ inputs.runner }}
+    environment:
+      name: github-pages
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Configure GitHub Pages
+        id: configure
+        uses: actions/configure-pages@v5
+      - name: Deploy GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

build-sphinx-docs/README.md

@@ -0,0 +1,107 @@
+# Build Sphinx documentation workflow
+
+This reusable workflow enables developers to build and upload Sphinx-generated
+documentation from a local repository to GitHub Pages.
+
+## Usage
+
+To use this workflow developers must have a `requirements.txt` file to define 
+the sphinx dependencies that will be used by the `build-sphinx-docs` workflow. 
+By default the workflow will look for a `requirements.txt` file in the top 
+level of the calling project repository. An example of a `requirements.txt`
+file which could run this workflow would be as follows:
+
+### Example requirements
+
+```text
+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
+```
+
+In this example file both the package name and version numbers of these packages
+have been specified. This workflow would still run if only the package names
+were specified and would by default install the most recent version of each
+package. However, it is recommended that version numbers are used in the
+`requirements.txt` file to ensure consistency across builds and to avoid
+automatic updates to packages breaking the workflow.
+
+To call this reusable workflow from a project repository a local workflow stored
+in the `.github/workflows` directory of the form described below is required:
+
+### Build Sphinx Documentation
+
+```yaml
+steps:
+  - name: Build Sphinx Documentation
+    uses: MetOffice/growss/.github/workflows/build-sphinx-docs.yaml@main
+
+    with:
+      docs-directory: Directory containing the documentation source
+      requirements: Path to the requirements file to install dependencies from
+      sphinx-opts: Additional options to pass to the Sphinx build command
+      build-directory: Directory to output the html documentation to
+      runner: The runner to use for the job (ubuntu-latest)
+      timeout: Timeout for the job in minutes (5)
+```
+
+Here the user would implement this file and replace each of the parameters with
+the respective data types as dictated by the inputs section of the
+`build-sphinx-docs.yaml` file.
+
+Following the calling of the `build-sphinx-docs` workflow, the `deploy-sphinx-docs`
+workflow can be used to deploy the generated html documentation to the GitHub
+webserver. This workflow can be called from a workflow using the form describe below:
+
+### Deploy built HTML to GitHub Pages
+
+```yaml
+steps:
+  - name: Publish Documentation
+    uses: MetOffice/growss/.github/workflows/deploy-sphinx-docs.yaml@main
+
+    with:
+      runner: The runner to use for the job (ubuntu-latest)
+      timeout: Timeout for the job in minutes (5)
+```
+
+Both of these steps can be combined to produce a simple build and deploy documentation
+pipeline for a repository:
+
+### Example continuous intergration pipeline in an external repository
+
+An example workflow to build Sphinx documentation and deploy it to GitHub Pages
+when changes are pushed to the `main` branch:
+
+```yaml
+name: Build and Publish Docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build-docs:
+    name: Build sphinx docs
+    uses: MetOffice/growss/.github/workflows/build-sphinx-docs.yaml@main
+    with:
+      requirements: /path/to/requirements.txt
+      runner: ubuntu-24.04
+      timeout: 10
+      docs-directory: '/path/to/documentation'
+      sphinx-opts: 'extra options'
+      build-directory: '/path/to/build/html'
+
+  deploy-docs:
+    if: github.ref == 'refs/heads/main'
+    needs: build-docs
+    name: Deploy GitHub pages
+    uses: MetOffice/growss/.github/workflows/deploy-sphinx-docs.yaml@main
+    with:
+      runner: ubuntu-24.04
+      timeout: 5
+```