From 61cf5c820903c8730ecb041dad4d2890d2bd016a Mon Sep 17 00:00:00 2001 From: Shengliang Xu Date: Mon, 23 Mar 2026 16:53:35 +0000 Subject: [PATCH 1/2] Make a document preview for PRs Make it much easier for reviewing changes on docs. Signed-off-by: Shengliang Xu --- .github/workflows/pages.yml | 30 ++++++++++++++++++------------ .github/workflows/pr-preview.yml | 28 ++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/pr-preview.yml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 7e18e25d770..281ee5ca164 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -14,11 +14,9 @@ concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} cancel-in-progress: true -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +# contents: write required to push to gh-pages branch permissions: - contents: read - pages: write - id-token: write + contents: write jobs: build-docs: @@ -30,18 +28,26 @@ jobs: - name: Build docs run: pip install tox && tox -e build-docs - name: Upload docs artifact - if: github.event_name == 'push' - uses: actions/upload-pages-artifact@v4 + if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + uses: actions/upload-artifact@v4 with: + name: docs-html path: docs/build/html deploy-gh-pages: - if: github.event_name == 'push' + if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' needs: build-docs runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} steps: - - id: deployment - uses: actions/deploy-pages@v4 + - uses: actions/checkout@v6 + - name: Download docs artifact + uses: actions/download-artifact@v4 + with: + name: docs-html + path: docs/build/html + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/build/html + # Preserve PR preview subdirectories deployed by pr-preview.yml + clean-exclude: pr-preview diff --git a/.github/workflows/pr-preview.yml b/.github/workflows/pr-preview.yml new file mode 100644 index 00000000000..bd653649649 --- /dev/null +++ b/.github/workflows/pr-preview.yml @@ -0,0 +1,28 @@ +name: PR Docs Preview + +on: + pull_request: + types: [opened, synchronize, reopened, closed] + branches: [main, release/*, feature/*] + +# One preview deployment per PR; do not cancel so 'closed' cleanup always runs +concurrency: pr-preview-${{ github.event.pull_request.number }} + +permissions: + contents: write # push preview to gh-pages branch + pull-requests: write # post/update preview URL comment on the PR + +jobs: + deploy-preview: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v6 + - uses: ./.github/actions/ubuntu-setup + - name: Build docs + if: github.event.action != 'closed' + run: pip install tox && tox -e build-docs + - name: Deploy / remove PR preview + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: docs/build/html From 8ddaec55f945130e45fcf818b6290e9c4291cfb1 Mon Sep 17 00:00:00 2001 From: Shengliang Xu Date: Mon, 23 Mar 2026 17:40:32 +0000 Subject: [PATCH 2/2] Merging the preview into pages.yml given preview currently only has the pages preview logic Signed-off-by: Shengliang Xu --- .github/workflows/pages.yml | 25 ++++++++++++++++++++++--- .github/workflows/pr-preview.yml | 28 ---------------------------- 2 files changed, 22 insertions(+), 31 deletions(-) delete mode 100644 .github/workflows/pr-preview.yml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 281ee5ca164..6789142f97f 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -2,6 +2,7 @@ name: Docs on: pull_request: + types: [opened, synchronize, reopened, closed] branches: [main, release/*, feature/*] push: branches: [main] @@ -14,9 +15,9 @@ concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} cancel-in-progress: true -# contents: write required to push to gh-pages branch permissions: - contents: write + contents: write # push to gh-pages branch + pull-requests: write # post/update preview URL comment on PRs jobs: build-docs: @@ -34,6 +35,24 @@ jobs: name: docs-html path: docs/build/html + deploy-preview: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + timeout-minutes: 30 + # Per-PR concurrency without cancel-in-progress so 'closed' cleanup always runs + concurrency: + group: pr-preview-${{ github.event.pull_request.number }} + steps: + - uses: actions/checkout@v6 + - uses: ./.github/actions/ubuntu-setup + - name: Build docs + if: github.event.action != 'closed' + run: pip install tox && tox -e build-docs + - name: Deploy / remove PR preview + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: docs/build/html + deploy-gh-pages: if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' needs: build-docs @@ -49,5 +68,5 @@ jobs: uses: JamesIves/github-pages-deploy-action@v4 with: folder: docs/build/html - # Preserve PR preview subdirectories deployed by pr-preview.yml + # Preserve PR preview subdirectories deployed by the deploy-preview job clean-exclude: pr-preview diff --git a/.github/workflows/pr-preview.yml b/.github/workflows/pr-preview.yml deleted file mode 100644 index bd653649649..00000000000 --- a/.github/workflows/pr-preview.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: PR Docs Preview - -on: - pull_request: - types: [opened, synchronize, reopened, closed] - branches: [main, release/*, feature/*] - -# One preview deployment per PR; do not cancel so 'closed' cleanup always runs -concurrency: pr-preview-${{ github.event.pull_request.number }} - -permissions: - contents: write # push preview to gh-pages branch - pull-requests: write # post/update preview URL comment on the PR - -jobs: - deploy-preview: - runs-on: ubuntu-latest - timeout-minutes: 30 - steps: - - uses: actions/checkout@v6 - - uses: ./.github/actions/ubuntu-setup - - name: Build docs - if: github.event.action != 'closed' - run: pip install tox && tox -e build-docs - - name: Deploy / remove PR preview - uses: rossjrw/pr-preview-action@v1 - with: - source-dir: docs/build/html