improve directories layout: version subdirs and stable symlink (#18) #28
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: scheduled docs generation | |
| on: | |
| schedule: | |
| - cron: '0 5 * * *' | |
| workflow_dispatch: | |
| push: | |
| # Pages deployment requires pages:write and id-token:write. | |
| # contents:write is no longer needed since we no longer push to gh-pages directly. | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Prevent overlapping scheduled runs from deploying to GitHub Pages simultaneously. | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: false | |
| jobs: | |
| get-versions: | |
| runs-on: ubuntu-latest | |
| outputs: | |
| versions: ${{ steps.get-versions.outputs.versions }} | |
| steps: | |
| - name: Get supported Python versions | |
| id: get-versions | |
| run: | | |
| versions=$(curl -sf https://peps.python.org/api/release-cycle.json | \ | |
| jq -c '[to_entries[] | select(.value.status != "end-of-life" and .value.status != "planned") | {branch: (.value.branch // .key), python_version: (if .key == "3.10" then "3.12" else "3" end)}]') | |
| echo "versions=$versions" >> "$GITHUB_OUTPUT" | |
| build: | |
| needs: get-versions | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| include: ${{ fromJson(needs.get-versions.outputs.versions) }} | |
| # Build jobs run concurrently and upload artifacts per version. The single | |
| # deploy job below collects all artifacts and publishes once, avoiding | |
| # concurrent git pushes/commit conflicts to gh-pages. | |
| uses: ./.github/workflows/build.yaml | |
| with: | |
| reference: ${{ matrix.branch }} | |
| python_version: ${{ matrix.python_version }} | |
| publish: ${{ 'false' }} | |
| deploy: | |
| # A single deploy job runs after all build matrix jobs complete. | |
| # Artifacts from every concurrent build job are merged here and published | |
| # once via actions/deploy-pages, eliminating concurrent gh-pages push conflicts. | |
| needs: build | |
| if: ${{ !cancelled() && needs.build.result != 'failure' && github.event_name != 'push' }} | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Configure Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Checkout existing gh-pages content | |
| id: checkout-pages | |
| uses: actions/checkout@v5 | |
| with: | |
| ref: gh-pages | |
| path: _site | |
| continue-on-error: true | |
| - name: Prepare site directory | |
| run: | | |
| # Remove git metadata; safe even if checkout above did not succeed | |
| rm -rf _site/.git | |
| - name: Download all build artifacts | |
| # Collect artifacts uploaded by all concurrent build matrix jobs | |
| uses: actions/download-artifact@v4 | |
| with: | |
| path: artifacts/ | |
| - name: Copy new archives into site directory | |
| run: | | |
| # Copy generated archives (zip, tar.bz2, epub) into _site/<major_minor>/, | |
| # excluding PDF build logs which are for debugging only. | |
| # Extract major.minor from filenames like python-3.14.0-docs-html.zip. | |
| find artifacts/ -type f \( -name "*.zip" -o -name "*.tar.bz2" -o -name "*.epub" \) \ | |
| ! -name "python-*-pdf-logs.zip" | while read -r f; do | |
| filename=$(basename "$f") | |
| major_minor=$(echo "$filename" | sed -n 's/^python-\([0-9]*\.[0-9]*\).*/\1/p') | |
| mkdir -p "_site/$major_minor" | |
| cp "$f" "_site/$major_minor/" | |
| done | |
| - name: Symlink 3 to stable version | |
| run: | | |
| # Create a relative symlink _site/3 -> <stable> (e.g. 3 -> 3.14), | |
| # pointing to the first "bugfix" (stable) version from release-cycle JSON. | |
| stable=$(curl -sf https://peps.python.org/api/release-cycle.json | \ | |
| jq -r '[to_entries[] | select(.value.status == "bugfix")] | first | .key') | |
| if [ -z "$stable" ]; then | |
| echo "Error: no stable (bugfix) version found in release-cycle JSON" >&2 | |
| exit 1 | |
| fi | |
| # Remove existing 3 directory or symlink before creating new symlink | |
| rm -rf _site/3 | |
| ln -s "$stable" _site/3 | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: _site | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |