From c18d1aaf8756747d8ec633b600af685d64e64fe9 Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:14:34 +0200 Subject: [PATCH 1/7] Unify docs GH workflow --- .github/workflows/ci.yml | 29 +++----- .../workflows/{docs-deploy.yml => docs.yml} | 66 ++++++++++++++----- .github/workflows/release.yml | 47 +++---------- 3 files changed, 68 insertions(+), 74 deletions(-) rename .github/workflows/{docs-deploy.yml => docs.yml} (53%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b856dbd18..b0ef75f3a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -108,7 +108,7 @@ jobs: test: name: Test ${{ matrix.package }} - needs: [changes, formatting] + needs: [ changes, formatting ] if: needs.changes.outputs.packages != '[]' strategy: fail-fast: false @@ -129,34 +129,21 @@ 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 }}" + 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: diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs.yml similarity index 53% rename from .github/workflows/docs-deploy.yml rename to .github/workflows/docs.yml index 2d3c4eef8..150db9cc8 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs.yml @@ -1,28 +1,53 @@ -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 @@ -30,22 +55,37 @@ env: 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_name || 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 }} + - run: python -m pip install --upgrade pip + - run: python -m pip install -r requirements/ci.txt - name: Build docs run: pixi run docs-${{ inputs.package }} + - 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 +105,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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3d0632300..7de12f5b6 100644 --- a/.github/workflows/release.yml +++ b/.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,17 @@ jobs: packages-dir: dist/ docs: - name: Publish docs - needs: [determine-package, publish] - runs-on: ubuntu-24.04 - 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 + name: Build and publish docs + needs: [ determine-package, publish ] + 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 From a73826d438918919b7c7be5ab40e177faba7e85c Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:18:48 +0200 Subject: [PATCH 2/7] Add builder arg to docs commands --- pixi.toml | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/pixi.toml b/pixi.toml index 1da2693d6..c14c2b4d9 100644 --- a/pixi.toml +++ b/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 ==================== From c9ee94453712d75cd67ca2f10c0a67732d300581 Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:20:02 +0200 Subject: [PATCH 3/7] Run doctests and optionally linkcheck in CI --- .github/workflows/docs.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 150db9cc8..6e119d539 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -71,6 +71,11 @@ jobs: - run: python -m pip install -r requirements/ci.txt - 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: @@ -80,7 +85,7 @@ jobs: deploy: name: Deploy documentation - needs: docs + needs: [ docs ] runs-on: 'ubuntu-24.04' permissions: contents: write From 7ecd00e382a9b4ab6782eea31b6c9dbd1e062a8f Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:35:19 +0200 Subject: [PATCH 4/7] Allow write contents permission for docs --- .github/workflows/ci.yml | 2 ++ .github/workflows/release.yml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b0ef75f3a..283769c86 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -135,6 +135,8 @@ jobs: fail-fast: false matrix: package: ${{ fromJSON(needs.changes.outputs.packages) }} + permissions: + contents: write uses: ./.github/workflows/docs.yml with: package: ${{ matrix.package }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7de12f5b6..df87a9356 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -64,6 +64,8 @@ jobs: docs: name: Build and publish docs needs: [ determine-package, publish ] + permissions: + contents: write uses: ./.github/workflows/docs.yml with: package: ${{ needs.determine-package.outputs.package }} From eef4b4a496d4647b487199de582a7a88da31ce2a Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:37:26 +0200 Subject: [PATCH 5/7] Run tests when docs workflow changes --- .github/workflows/ci.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 283769c86..b8ec3e119 100644 --- a/.github/workflows/ci.yml +++ b/.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' From e5b4960343b1111d6afb5700f956688eb186c983 Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:53:55 +0200 Subject: [PATCH 6/7] Fix default ref --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6e119d539..a7ae585ba 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -60,7 +60,7 @@ jobs: steps: - uses: actions/checkout@v6 with: - ref: ${{ inputs.branch == '' && github.ref_name || inputs.branch }} + ref: ${{ inputs.branch == '' && github.ref || inputs.branch }} fetch-depth: 0 # history required to determine version - uses: prefix-dev/setup-pixi@v0.9.4 with: From 23f2fb1fe86a9ab6bbb63c82d187f9268d24930f Mon Sep 17 00:00:00 2001 From: Jan-Lukas Wynen Date: Fri, 22 May 2026 16:56:36 +0200 Subject: [PATCH 7/7] Remove bad pip install steps --- .github/workflows/docs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a7ae585ba..f7df3a5c8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -67,8 +67,6 @@ jobs: pixi-version: v0.68.0 frozen: true environments: docs-${{ inputs.package }} - - run: python -m pip install --upgrade pip - - run: python -m pip install -r requirements/ci.txt - name: Build docs run: pixi run docs-${{ inputs.package }} - name: Test docs