[CI] Unified docs CI workflow

.github/workflows/ci.yml

@@ -35,6 +35,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
             essimaging:
@@ -44,6 +45,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
             essnmx:
@@ -53,6 +55,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
             essreflectometry:
@@ -62,6 +65,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
             essdiffraction:
@@ -71,6 +75,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
             esssans:
@@ -80,6 +85,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
             essspectroscopy:
@@ -89,6 +95,7 @@ jobs:
               - 'pixi.lock'
               - 'pixi.toml'
               - '.github/workflows/ci.yml'
+              - '.github/workflows/docs.yml'
               - '.pre-commit-config.yaml'
               - '.python-version'
 
@@ -108,7 +115,7 @@ jobs:
 
   test:
     name: Test ${{ matrix.package }}
-    needs: [changes, formatting]
+    needs: [ changes, formatting ]
     if: needs.changes.outputs.packages != '[]'
     strategy:
       fail-fast: false
@@ -129,34 +136,23 @@ jobs:
 
   docs:
     name: Docs ${{ matrix.package }}
-    needs: [changes, test]
+    needs: [ changes, test ]
     if: needs.changes.outputs.packages != '[]'
     strategy:
       fail-fast: false
       matrix:
         package: ${{ fromJSON(needs.changes.outputs.packages) }}
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - uses: prefix-dev/setup-pixi@v0.9.4
-        with:
-          pixi-version: v0.68.0
-          frozen: true
-          environments: docs-${{ matrix.package }}
-      - name: Build docs
-        run: pixi run docs-${{ matrix.package }}
-      - uses: actions/upload-artifact@v7
-        id: artifact-upload-step
-        with:
-          name: docs-${{ matrix.package }}
-          path: packages/${{ matrix.package }}/html
-      - run: echo "::notice::https://remote-unzip.scipp.deno.net/${{ github.repository }}/artifacts/${{ steps.artifact-upload-step.outputs.artifact-id }}"
+    permissions:
+      contents: write
+    uses: ./.github/workflows/docs.yml
+    with:
+      package: ${{ matrix.package }}
+      publish: false
+      linkcheck: false
 
   report:
     name: Report Job Status
-    needs: [changes, formatting, test, docs]
+    needs: [ changes, formatting, test, docs ]
     if: always()  # Should always run regardless of the state of the needs jobs.
     runs-on: ubuntu-24.04
     steps:

.github/workflows/docs-deploy.yml → .github/workflows/docs.yml

@@ -1,51 +1,94 @@
-name: Deploy docs
+name: Docs
 
 on:
   workflow_dispatch:
     inputs:
       package:
+        description: 'Package to build documentation for.'
         required: true
-        description: 'Select which package to build docs for'
         type: choice
         options:
           - essreduce
           - essimaging
           - essnmx
-          - essdiffraction
           - essreflectometry
+          - essdiffraction
           - esssans
           - essspectroscopy
+      publish:
+        description: 'Publish documentation to GitHub pages.'
+        default: false
+        type: boolean
+      branch:
+        description: 'Branch/tag with documentation source. If not set, the current branch will be used.'
+        default: ''
+        required: false
+        type: string
+      linkcheck:
+        description: 'Run the link checker.'
+        default: true
+        required: false
+        type: boolean
+  workflow_call:
+    inputs:
+      package:
+        description: 'Package to build documentation for.'
+        required: true
+        type: string
       publish:
         default: false
         type: boolean
       branch:
-        description: 'Branch/tag with documentation source. If not set, the main branch will be used.'
-        default: 'main'
+        description: 'Branch/tag with documentation source. If not set, the current branch will be used.'
+        default: ''
         required: false
         type: string
+      linkcheck:
+        description: 'Run the link checker. If not set the link checker will not be run.'
+        default: false
+        required: false
+        type: boolean
 
 env:
   PIXI_FROZEN: true
   PIXI_NO_INSTALL: true
 
 jobs:
   docs:
-    name: Build and deploy docs
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: write
+    name: Build documentation
+    runs-on: 'ubuntu-24.04'
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{ inputs.branch }}
-          fetch-depth: 0
+          ref: ${{ inputs.branch == '' && github.ref || inputs.branch }}
+          fetch-depth: 0  # history required to determine version
       - uses: prefix-dev/setup-pixi@v0.9.4
         with:
           pixi-version: v0.68.0
           frozen: true
           environments: docs-${{ inputs.package }}
       - name: Build docs
         run: pixi run docs-${{ inputs.package }}
+      - name: Test docs
+        run: pixi run docs-${{ inputs.package }} doctest
+      - name: Linkcheck
+        run: pixi run docs-${{ inputs.package }} linkcheck
+        if: ${{ inputs.linkcheck }}
+      - uses: actions/upload-artifact@v7
+        id: artifact-upload-step
+        with:
+          name: docs-${{ inputs.package }}
+          path: packages/${{ inputs.package }}/html
+      - run: echo "::notice::https://remote-unzip.scipp.deno.net/${{ github.repository }}/artifacts/${{ steps.artifact-upload-step.outputs.artifact-id }}"
+
+  deploy:
+    name: Deploy documentation
+    needs: [ docs ]
+    runs-on: 'ubuntu-24.04'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v7
       - name: Prepare site
         if: ${{ inputs.publish }}
         run: |
@@ -65,7 +108,3 @@ jobs:
         with:
           branch: gh-pages
           folder: gh-pages-site
-      - uses: actions/upload-artifact@v7
-        with:
-          name: docs-${{ inputs.package }}
-          path: packages/${{ inputs.package }}/html

.github/workflows/release.yml

@@ -47,7 +47,7 @@ jobs:
 
   publish:
     name: Publish to PyPI
-    needs: [determine-package, build]
+    needs: [ determine-package, build ]
     runs-on: ubuntu-24.04
     environment: release
     permissions:
@@ -62,46 +62,19 @@ jobs:
           packages-dir: dist/
 
   docs:
-    name: Publish docs
-    needs: [determine-package, publish]
-    runs-on: ubuntu-24.04
+    name: Build and publish docs
+    needs: [ determine-package, publish ]
     permissions:
       contents: write
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - uses: prefix-dev/setup-pixi@v0.9.4
-        with:
-          pixi-version: v0.68.0
-          frozen: true
-          environments: docs-${{ needs.determine-package.outputs.package }}
-      - name: Build docs
-        run: pixi run docs-${{ needs.determine-package.outputs.package }}
-      - name: Prepare site
-        run: |
-          PACKAGE=${{ needs.determine-package.outputs.package }}
-          SUBPATH=${PACKAGE#ess}
-          git fetch origin gh-pages:gh-pages || true
-          git worktree add gh-pages-site gh-pages || mkdir -p gh-pages-site
-          rm -rf gh-pages-site/$SUBPATH
-          cp -r packages/$PACKAGE/html gh-pages-site/$SUBPATH
-          cp docs/index.html gh-pages-site/index.html
-          touch gh-pages-site/.nojekyll
-      - name: Build search index
-        run: npx pagefind@latest --site gh-pages-site --bundle-dir pagefind
-      - uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          branch: gh-pages
-          folder: gh-pages-site
-      - uses: actions/upload-artifact@v7
-        with:
-          name: docs_html
-          path: packages/${{ needs.determine-package.outputs.package }}/html
+    uses: ./.github/workflows/docs.yml
+    with:
+      package: ${{ needs.determine-package.outputs.package }}
+      publish: true
+      linkcheck: false
 
   assets:
     name: Upload docs
-    needs: [docs, determine-package]
+    needs: [ docs, determine-package ]
     runs-on: ubuntu-24.04
     permissions:
       contents: write

pixi.toml

@@ -89,44 +89,65 @@ python-graphviz = "*"
 essreduce = { path = "packages/essreduce", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-essreduce.tasks.docs-essreduce]
-cmd = "python -m sphinx -v -b html -d packages/essreduce/.docs_doctrees packages/essreduce/docs packages/essreduce/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/essreduce/.docs_doctrees packages/essreduce/docs packages/essreduce/html"
 default-environment = "docs-essreduce"
 
 [feature.docs-essimaging.pypi-dependencies]
 essimaging = { path = "packages/essimaging", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-essimaging.tasks.docs-essimaging]
-cmd = "python -m sphinx -v -b html -d packages/essimaging/.docs_doctrees packages/essimaging/docs packages/essimaging/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/essimaging/.docs_doctrees packages/essimaging/docs packages/essimaging/html"
 
 [feature.docs-essnmx.pypi-dependencies]
 essnmx = { path = "packages/essnmx", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-essnmx.tasks.docs-essnmx]
-cmd = "python -m sphinx -v -b html -d packages/essnmx/.docs_doctrees packages/essnmx/docs packages/essnmx/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/essnmx/.docs_doctrees packages/essnmx/docs packages/essnmx/html"
 
 [feature.docs-essreflectometry.pypi-dependencies]
 essreflectometry = { path = "packages/essreflectometry", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-essreflectometry.tasks.docs-essreflectometry]
-cmd = "python -m sphinx -v -b html -d packages/essreflectometry/.docs_doctrees packages/essreflectometry/docs packages/essreflectometry/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/essreflectometry/.docs_doctrees packages/essreflectometry/docs packages/essreflectometry/html"
 
 [feature.docs-essdiffraction.pypi-dependencies]
 essdiffraction = { path = "packages/essdiffraction", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-essdiffraction.tasks.docs-essdiffraction]
-cmd = "python -m sphinx -v -b html -d packages/essdiffraction/.docs_doctrees packages/essdiffraction/docs packages/essdiffraction/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/essdiffraction/.docs_doctrees packages/essdiffraction/docs packages/essdiffraction/html"
 
 [feature.docs-esssans.pypi-dependencies]
 esssans = { path = "packages/esssans", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-esssans.tasks.docs-esssans]
-cmd = "python -m sphinx -v -b html -d packages/esssans/.docs_doctrees packages/esssans/docs packages/esssans/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/esssans/.docs_doctrees packages/esssans/docs packages/esssans/html"
 
 [feature.docs-essspectroscopy.pypi-dependencies]
 essspectroscopy = { path = "packages/essspectroscopy", editable = true, extras = ["test", "docs"] }
 
 [feature.docs-essspectroscopy.tasks.docs-essspectroscopy]
-cmd = "python -m sphinx -v -b html -d packages/essspectroscopy/.docs_doctrees packages/essspectroscopy/docs packages/essspectroscopy/html"
+args = [
+    { "arg" = "builder", "default" = "html" },
+]
+cmd = "python -m sphinx -v -b {{ builder }} -d packages/essspectroscopy/.docs_doctrees packages/essspectroscopy/docs packages/essspectroscopy/html"
 
 # ==================== Environments ====================