Use sphinx docs

.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 2.6.0
+_commit: 4.0.1
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: martin.gaughran@diamond.ac.uk
 author_name: Martin Gaughran
@@ -9,10 +9,11 @@ component_type: library
 description: A set of tools used for deploying applications to a shared filesystem.
 distribution_name: dls-deploy-tools
 docker: true
-docs_type: README
+docs_type: sphinx
 git_platform: github.com
 github_org: DiamondLightSource
 package_name: deploy_tools
 pypi: true
 repo_name: deploy-tools
+strict_typing: true
 type_checker: pyright

.github/CONTRIBUTING.md

@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.6.0/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/4.0.1/how-to.html).

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,7 +7,7 @@ assignees: ''
 
 ---
 
-Describe the bug, including a clear and concise description of the expected behavior, the actual behavior and the context in which you encountered it (ideally include details of your environment).
+Describe the bug, including a clear and concise description of the expected behaviour, the actual behavior and the context in which you encountered it (ideally include details of your environment).
 
 ## Steps To Reproduce
 Steps to reproduce the behavior:

.github/actions/install_requirements/action.yml

@@ -15,7 +15,8 @@ runs:
       run: |
         PYTHON_VERSION="${{ inputs.python-version }}"
         if [ $PYTHON_VERSION == "dev" ]; then
-          PYTHON_VERSION=$(sed -n "s/ARG PYTHON_VERSION=//p" Dockerfile)
+          # python version from Dockerfile, removing potential pinned sha
+          PYTHON_VERSION=$(sed -Ene "s/ARG PYTHON_VERSION=([0-9\.]+).*/\1/p" Dockerfile)
         fi
         echo "PYTHON_VERSION=$PYTHON_VERSION" >> "$GITHUB_ENV"
       shell: bash

.github/dependabot.yml

@@ -13,6 +13,8 @@ updates:
       actions:
         patterns:
           - "*"
+    commit-message:
+      prefix: "chore"
 
   - package-ecosystem: "pip"
     directory: "/"
@@ -22,3 +24,5 @@ updates:
       dev-dependencies:
         patterns:
           - "*"
+    commit-message:
+      prefix: "chore"

.github/workflows/_container.yml

@@ -1,5 +1,9 @@
 on:
   workflow_call:
+    inputs:
+      publish:
+        type: boolean
+        description: If true, pushes image to container registry
 
 jobs:
   build:
@@ -47,7 +51,7 @@ jobs:
             type=raw,value=latest
 
       - name: Push cached image to container registry
-        if: github.ref_type == 'tag'
+        if: inputs.publish && github.ref_type == 'tag'
         uses: docker/build-push-action@v6
         env:
           DOCKER_BUILD_RECORD_UPLOAD: false

.github/workflows/_docs.yml

@@ -0,0 +1,55 @@
+on:
+  workflow_call:
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Avoid git conflicts when tag and branch pushed at same time
+        if: github.ref_type == 'tag'
+        run: sleep 60
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need this to get version number from last tag
+          fetch-depth: 0
+
+      - name: Install system packages
+        run: sudo apt-get install graphviz
+
+      - name: Install python packages
+        uses: ./.github/actions/install_requirements
+
+      - name: Build docs
+        run: tox -e docs
+
+      - name: Remove environment.pickle
+        run: rm build/html/.doctrees/environment.pickle
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: build
+
+      - name: Sanitize ref name for docs version
+        run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+      - name: Move to versioned directory
+        run: mv build/html .github/pages/$DOCS_VERSION
+
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Publish Docs to gh-pages
+        if: github.ref_type == 'tag' || github.ref_name == 'main'
+        # We pin to the SHA, not the tag, for security reasons.
+        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .github/pages
+          keep_files: true

.github/workflows/_release.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Create GitHub Release
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.0.9
+        uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
           files: "*"

.github/workflows/_test.yml

@@ -60,7 +60,7 @@ jobs:
           tox -e tests
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
           name: ${{ inputs.python-version }}/${{ inputs.runs-on }}
           files: cov.xml

.github/workflows/ci.yml

@@ -2,26 +2,24 @@ name: CI
 
 on:
   push:
+    branches:
+      - main
+    tags:
+      - '*'
   pull_request:
 
 jobs:
-  check:
-    uses: ./.github/workflows/_check.yml
 
   lint:
-    needs: check
-    if: needs.check.outputs.branch-pr == ''
     uses: ./.github/workflows/_tox.yml
     with:
       tox: pre-commit,type-checking
 
   test:
-    needs: check
-    if: needs.check.outputs.branch-pr == ''
     strategy:
       matrix:
         runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
-        python-version: ["3.12"]
+        python-version: ["3.12", "3.13"]
         include:
           # Include one that runs in the dev environment
           - runs-on: "ubuntu-latest"
@@ -35,28 +33,32 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   container:
-    needs: check
-    if: needs.check.outputs.branch-pr == ''
+    needs: test
+    if: always()
     uses: ./.github/workflows/_container.yml
+    with:
+      publish: ${{ needs.test.result == 'success' }}
     permissions:
       contents: read
       packages: write
 
+  docs:
+    uses: ./.github/workflows/_docs.yml
+
+
   dist:
-    needs: check
-    if: needs.check.outputs.branch-pr == ''
     uses: ./.github/workflows/_dist.yml
 
   pypi:
+    needs: [dist, test]
     if: github.ref_type == 'tag'
-    needs: dist
     uses: ./.github/workflows/_pypi.yml
     permissions:
       id-token: write
 
   release:
+    needs: [dist, test, docs]
     if: github.ref_type == 'tag'
-    needs: [dist]
     uses: ./.github/workflows/_release.yml
     permissions:
       contents: write

.github/workflows/periodic.yml

@@ -0,0 +1,13 @@
+name: Periodic
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run weekly to check URL links still resolve
+    - cron: "0 8 * * WED"
+
+jobs:
+  linkcheck:
+    uses: ./.github/workflows/_tox.yml
+    with:
+      tox: docs build -- -b linkcheck

.pre-commit-config.yaml

@@ -12,7 +12,7 @@ repos:
       - id: ruff
         name: lint with ruff
         language: system
-        entry: ruff check --force-exclude
+        entry: ruff check --force-exclude --fix
         types: [python]
         require_serial: true
 

.vscode/launch.json

@@ -14,10 +14,6 @@
                 "debug-test"
             ],
             "console": "integratedTerminal",
-            "env": {
-                // Enable break on exception when debugging tests (see: tests/conftest.py)
-                "PYTEST_RAISE": "1",
-            },
         },
         {
             "name": "Debug Schema Generation",
@@ -27,10 +23,6 @@
             "program": "/venv/bin/deploy-tools",
             "args": "schema ${input:schema-folder}",
             "console": "integratedTerminal",
-            "env": {
-                // Enable break on exception when debugging tests (see: tests/conftest.py)
-                "PYTEST_RAISE": "1",
-            },
         },
         {
             "name": "Debug Validation",
@@ -40,10 +32,6 @@
             "program": "/venv/bin/deploy-tools",
             "args": "validate ${input:allow-all} ${input:from-scratch} ${input:test-build} ${input:deploy-folder} ${input:config-folder}",
             "console": "integratedTerminal",
-            "env": {
-                // Enable break on exception when debugging tests (see: tests/conftest.py)
-                "PYTEST_RAISE": "1",
-            },
         },
         {
             "name": "Debug Compare",
@@ -53,10 +41,6 @@
             "program": "/venv/bin/deploy-tools",
             "args": "compare ${input:compare-mode} ${input:deploy-folder}",
             "console": "integratedTerminal",
-            "env": {
-                // Enable break on exception when debugging tests (see: tests/conftest.py)
-                "PYTEST_RAISE": "1",
-            },
         },
         {
             "name": "Debug Sync",
@@ -66,10 +50,6 @@
             "program": "/venv/bin/deploy-tools",
             "args": "sync ${input:allow-all} ${input:from-scratch} ${input:deploy-folder} ${input:config-folder}",
             "console": "integratedTerminal",
-            "env": {
-                // Enable break on exception when debugging tests (see: tests/conftest.py)
-                "PYTEST_RAISE": "1",
-            },
         },
     ],
     "inputs": [

README.md

@@ -16,6 +16,7 @@ Source          | <https://github.com/DiamondLightSource/deploy-tools>
 :---:           | :---:
 PyPI            | `pip install dls-deploy-tools`
 Docker          | `docker run ghcr.io/diamondlightsource/deploy-tools:latest`
+Documentation   | <https://diamondlightsource.github.io/deploy-tools>
 Releases        | <https://github.com/DiamondLightSource/deploy-tools/releases>
 
 The demo_configuration folder in this repository can be passed as the config_folder to
@@ -109,3 +110,7 @@ See the Deployment Steps above for an overview of the primary stages of a deploy
 |Deprecate          |Moving a modulefile to the separate Deprecated Folder, to indicate that its use should be discouraged                                                                                                                                                                                                       |
 |Deprecated Folder  |The folder used to contain Modulefiles for Modules that have been deprecated. By adding the modulefiles subdirectory to your MODULEPATH environment variable, you then have the ability to use any deprecated Module as normal.                                                                             |
 |End User           |Refers to anybody who is intending to make use of a deployed Module. This can include the people modifying configuration themselves                                                                                                                                                                         |
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://diamondlightsource.github.io/deploy-tools for more detailed documentation.

docs/_api.rst

@@ -0,0 +1,16 @@
+:orphan:
+
+..
+   This page is not included in the TOC tree, but must exist so that the
+   autosummary pages are generated for deploy_tools and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    deploy_tools