From 2a8a3b2d775660470e26a55aba78811d783e5d35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Sun, 3 May 2026 00:42:01 +0200 Subject: [PATCH] docs: add /next-version-preview/ subpath via gh-pages branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs site can now host two slots side by side: https://wordpress.github.io/php-toolkit/ ← trunk https://wordpress.github.io/php-toolkit/next-version-preview/ ← latest preview Both live on a single `gh-pages` branch: gh-pages:/ trunk site (root) gh-pages:/next-version-preview/ whichever branch was most-recently built by docs-preview.yml Mechanism: - docs.yml stops using actions/upload-pages-artifact + actions/deploy-pages (which replace the entire site on every deploy) and switches to peaceiris/actions-gh-pages@v4 with `keep_files: true`. Trunk pushes to the branch root and leaves the preview directory untouched. - docs-preview.yml is new: triggered manually (workflow_dispatch with a `ref` input) or by pushing to a `preview/*` branch namespace. It rebuilds the docs site from the chosen ref, then peaceiris publishes to `gh-pages/next-version-preview/` with destination_dir scoping so only that subfolder is replaced. - If the previewed ref has an open PR, the workflow drops a comment with the preview URL on it. Concurrency group `gh-pages` is shared between both workflows so two deploys can't race for the same branch (`cancel-in-progress: false` queues them rather than dropping work). Build steps tolerate either build-docs.py or build-reference.py being absent so the workflows keep working through the catalog refactor (the markdown-source PR retires build-docs.py). After this PR merges, the repo's Pages source needs to flip from "GitHub Actions" to "Deploy from a branch (gh-pages /)" — done out of band via the Pages API once the first gh-pages push lands. --- .github/workflows/docs-preview.yml | 106 +++++++++++++++++++++++++++++ .github/workflows/docs.yml | 50 ++++++++------ 2 files changed, 137 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/docs-preview.yml diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml new file mode 100644 index 000000000..516755694 --- /dev/null +++ b/.github/workflows/docs-preview.yml @@ -0,0 +1,106 @@ +name: Deploy docs preview + +# Publishes a "next version" preview of the docs site at +# https://wordpress.github.io/php-toolkit/next-version-preview/ +# +# Trigger options: +# - Manually via the Actions tab (workflow_dispatch). Pick any branch / +# SHA via the `ref` input. Useful for previewing in-flight work that +# isn't tied to a single PR. +# - Push to a `preview/*` branch. Lets a contributor put up a preview +# by pushing `git push origin HEAD:preview/my-thing` without ever +# opening a PR. +# +# A single preview slot lives at /next-version-preview/. Whatever ran +# this workflow most recently is what readers see there. Each deploy +# replaces the contents of that subdirectory; the rest of gh-pages +# (notably the trunk site at /) is preserved via keep_files: true. + +on: + workflow_dispatch: + inputs: + ref: + description: 'Git ref to build (branch, tag, or SHA)' + required: true + default: 'trunk' + push: + branches: + - 'preview/*' + +permissions: + contents: write # peaceiris pushes to gh-pages + pull-requests: write # used to comment the preview URL on a PR + pages: read + +concurrency: + group: gh-pages + cancel-in-progress: false + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout requested ref + uses: actions/checkout@v4 + with: + ref: ${{ github.event.inputs.ref || github.ref }} + + - name: Set up PHP + uses: shivammathur/setup-php@v2 + with: + php-version: '8.1' + tools: composer + coverage: none + + - name: Install dependencies + run: composer install --no-dev --optimize-autoloader --no-progress + + - name: Bundle toolkit and regenerate docs + run: | + mkdir -p docs/assets + rm -f docs/assets/php-toolkit.zip + zip -qr docs/assets/php-toolkit.zip components vendor bootstrap.php composer.json \ + -x "*/Tests/*" "*/tests/*" "*/.git/*" "*/.github/*" "*/node_modules/*" + if [ -f bin/build-docs.py ]; then python3 bin/build-docs.py; fi + if [ -f bin/build-reference.py ]; then python3 bin/build-reference.py; fi + + - name: Deploy to gh-pages /next-version-preview/ + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + publish_branch: gh-pages + destination_dir: next-version-preview + # Within the destination_dir scope, replace contents fully so a + # preview always reflects only what was just built. + keep_files: false + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' + commit_message: 'docs(preview): deploy ${{ github.event.inputs.ref || github.ref_name }} @ ${{ github.sha }}' + + - name: Find PR for this ref + id: find_pr + if: github.event_name == 'workflow_dispatch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REF: ${{ github.event.inputs.ref }} + run: | + # If the requested ref is a branch with an open PR, capture its + # number so we can drop a preview-link comment. + PR_NUMBER=$(gh pr list --state open --head "${REF}" --json number --jq '.[0].number // empty' || true) + if [ -n "$PR_NUMBER" ]; then + echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT" + fi + + - name: Comment preview URL on PR + if: steps.find_pr.outputs.pr_number != '' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ steps.find_pr.outputs.pr_number }} + REF: ${{ github.event.inputs.ref || github.ref_name }} + run: | + gh pr comment "$PR_NUMBER" --body "📚 Preview deployed from \`${REF}\`: https://wordpress.github.io/php-toolkit/next-version-preview/" + + - name: Print preview URL + run: | + echo "Preview deployed: https://wordpress.github.io/php-toolkit/next-version-preview/" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2fb740ede..8faf518d8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,5 +1,10 @@ name: Deploy docs to GitHub Pages +# Builds the runnable docs site from `trunk` and pushes the result to the +# `gh-pages` branch root. The branch is also where preview deploys land +# (under `next-version-preview/`); this workflow uses `keep_files: true` +# so trunk deploys never wipe out a sibling preview. + on: push: branches: [trunk] @@ -7,22 +12,25 @@ on: - 'components/**' - 'docs/**' - 'bin/build-docs*' + - 'bin/build-reference.py' + - 'bin/_docs_components.py' + - 'bin/_docs_components/**' + - 'bin/_load_catalog.py' - 'composer.json' - 'composer.lock' - '.github/workflows/docs.yml' workflow_dispatch: permissions: - contents: read - pages: write - id-token: write + contents: write # required: peaceiris pushes to the gh-pages branch + pages: read concurrency: - group: pages - cancel-in-progress: true + group: gh-pages + cancel-in-progress: false jobs: - build: + build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -43,18 +51,22 @@ jobs: rm -f docs/assets/php-toolkit.zip zip -qr docs/assets/php-toolkit.zip components vendor bootstrap.php composer.json \ -x "*/Tests/*" "*/tests/*" "*/.git/*" "*/.github/*" "*/node_modules/*" - python3 bin/build-docs.py + # Regenerate every page the catalog drives. build-docs.py and + # build-reference.py both exist for now; tolerate either being + # absent so this workflow keeps working through the catalog + # refactor (PR #254). + if [ -f bin/build-docs.py ]; then python3 bin/build-docs.py; fi + if [ -f bin/build-reference.py ]; then python3 bin/build-reference.py; fi - - uses: actions/upload-pages-artifact@v3 + - name: Deploy to gh-pages root + uses: peaceiris/actions-gh-pages@v4 with: - path: ./docs - - deploy: - needs: build - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - id: deployment - uses: actions/deploy-pages@v4 + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + publish_branch: gh-pages + # Preserve preview content (e.g. next-version-preview/) on the + # branch — trunk deploys only own the root. + keep_files: true + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' + commit_message: 'docs: deploy from trunk @ ${{ github.sha }}'