From 84e84bff45796714457edea0cceba8f8228965d7 Mon Sep 17 00:00:00 2001 From: Ben van Werkhoven Date: Sat, 7 Nov 2026 11:06:21 +0100 Subject: [PATCH 1/2] build documentation with Python 3.12 Pillow 13.0.0 and tornado 6.6 in doc/requirements.txt require Python >= 3.11, which broke the documentation workflows that still used Python 3.10. --- .github/workflows/docs-on-release.yml | 4 ++-- .github/workflows/docs.yml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-on-release.yml b/.github/workflows/docs-on-release.yml index da5b05cdd..649de4475 100644 --- a/.github/workflows/docs-on-release.yml +++ b/.github/workflows/docs-on-release.yml @@ -12,10 +12,10 @@ jobs: environment: dev_environment runs-on: ubuntu-latest steps: - - name: Get Python 3.10 + - name: Get Python 3.12 uses: actions/setup-python@v4 with: - python-version: "3.10" + python-version: "3.12" - name: Checkout uses: actions/checkout@v4 with: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3d53495ff..5295f5dcc 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -15,7 +15,7 @@ jobs: steps: - uses: actions/setup-python@v4 with: - python-version: "3.10" + python-version: "3.12" - name: Checkout uses: actions/checkout@v4 with: From 7c2a30783ebbbd67607697ee11b33c5f24b3b3d2 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sat, 7 Nov 2026 16:11:38 +0100 Subject: [PATCH 2/2] replace deprecated actions in documentation workflows Update actions/checkout and actions/setup-python to v7 (Node 24). Replace sphinx-notes/pages@v2 (node12) with explicit build and commit steps, because v3 deploys through GitHub Pages artifacts and would drop the versioned directories on the gh-pages branch. Replace ad-m/github-push-action@master with a plain git push. Sphinx now runs with the exact versions pinned in doc/requirements.txt. --- .github/workflows/docs-on-release.yml | 41 ++++++++++++++++---------- .github/workflows/docs.yml | 42 +++++++++++++++++---------- 2 files changed, 53 insertions(+), 30 deletions(-) diff --git a/.github/workflows/docs-on-release.yml b/.github/workflows/docs-on-release.yml index 649de4475..6f9ba9af9 100644 --- a/.github/workflows/docs-on-release.yml +++ b/.github/workflows/docs-on-release.yml @@ -7,19 +7,22 @@ on: # Allows you to run this workflow manually from the Actions tab workflow_dispatch: +permissions: + contents: write # needed to push the built documentation to the gh-pages branch + jobs: build: environment: dev_environment runs-on: ubuntu-latest steps: - name: Get Python 3.12 - uses: actions/setup-python@v4 + uses: actions/setup-python@v7 with: python-version: "3.12" - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v7 with: - fetch-depth: 0 # otherwise, you will failed to push refs to dest repo + fetch-depth: 0 # also fetches the gh-pages branch - name: Get version set env, exit if beta release run: | echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV @@ -29,24 +32,32 @@ jobs: fi - name: Install dependencies run: | - sudo apt-get update; - sudo apt-get install pandoc; + sudo apt-get update + sudo apt-get install pandoc pip install -e . - - name: Build and Commit - uses: sphinx-notes/pages@v2 - with: - requirements_path: doc/requirements.txt - documentation_path: doc/source - target_path: ${{ env.RELEASE_VERSION }} + pip install -r doc/requirements.txt + - name: Build documentation + run: sphinx-build -b html doc/source "$RUNNER_TEMP/html" + - name: Commit documentation to gh-pages + run: | + git config --global user.name "GitHub Action" + git config --global user.email "action@github.com" + git worktree add -B gh-pages "$RUNNER_TEMP/gh-pages" origin/gh-pages + cd "$RUNNER_TEMP/gh-pages" + rm -rf "$RELEASE_VERSION" + mkdir -p "$RELEASE_VERSION" + cp -r "$RUNNER_TEMP/html/." "$RELEASE_VERSION" + rm -rf "$RELEASE_VERSION/.doctrees" + touch "$RELEASE_VERSION/.nojekyll" + git add -A "$RELEASE_VERSION" + git commit --allow-empty -m "Add changes for $GITHUB_SHA" - name: Redirect stable to new release run: | echo "Redirecting stable to newly released version " $RELEASE_VERSION + cd "$RUNNER_TEMP/gh-pages" rm -rf stable ln -s $RELEASE_VERSION stable git add stable git commit -m "redirect stable to new version $RELEASE_VERSION" - name: Push changes - uses: ad-m/github-push-action@master - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages + run: git -C "$RUNNER_TEMP/gh-pages" push origin gh-pages diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5295f5dcc..38fef9917 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -7,32 +7,44 @@ on: # Allows you to run this workflow manually from the Actions tab workflow_dispatch: +permissions: + contents: write # needed to push the built documentation to the gh-pages branch + jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest steps: - - uses: actions/setup-python@v4 + - uses: actions/setup-python@v7 with: python-version: "3.12" - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v7 with: - fetch-depth: 0 # otherwise, you will failed to push refs to dest repo + fetch-depth: 0 # also fetches the gh-pages branch - name: Install dependencies run: | - sudo apt-get update; - sudo apt-get install pandoc; + sudo apt-get update + sudo apt-get install pandoc pip install -e . - - name: Build and Commit - uses: sphinx-notes/pages@v2 - with: - requirements_path: doc/requirements.txt - documentation_path: doc/source - target_path: latest + pip install -r doc/requirements.txt + - name: Build documentation + run: sphinx-build -b html doc/source "$RUNNER_TEMP/html" + - name: Commit documentation to gh-pages + env: + TARGET_PATH: latest + run: | + git config --global user.name "GitHub Action" + git config --global user.email "action@github.com" + git worktree add -B gh-pages "$RUNNER_TEMP/gh-pages" origin/gh-pages + cd "$RUNNER_TEMP/gh-pages" + rm -rf "$TARGET_PATH" + mkdir -p "$TARGET_PATH" + cp -r "$RUNNER_TEMP/html/." "$TARGET_PATH" + rm -rf "$TARGET_PATH/.doctrees" + touch "$TARGET_PATH/.nojekyll" + git add -A "$TARGET_PATH" + git commit --allow-empty -m "Add changes for $GITHUB_SHA" - name: Push changes - uses: ad-m/github-push-action@master - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages + run: git -C "$RUNNER_TEMP/gh-pages" push origin gh-pages