Merge pull request #390 from kmarchais/release/v0.17.0 #1034
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: Documentation | |
| on: | |
| push: | |
| branches: [main] | |
| pull_request: | |
| branches: [main] | |
| permissions: | |
| contents: write | |
| pull-requests: write | |
| # Prevent concurrent deploys from corrupting gh-pages | |
| concurrency: | |
| group: docs-deploy | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v7 | |
| with: | |
| fetch-depth: 0 | |
| - name: Setup uv | |
| uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1 | |
| with: | |
| enable-cache: true | |
| - name: Setup Python | |
| run: uv python install 3.12 | |
| - name: Cache apt packages | |
| uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3 | |
| with: | |
| packages: libvtk9-dev qtbase5-dev qt5-qmake libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev | |
| version: 1.0 | |
| - name: Install dependencies | |
| run: uv sync --group docs | |
| - name: Configure Git for mike | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| # One-time migration: wipe legacy gh-pages from mkdocs gh-deploy | |
| # so mike starts with a clean branch (safe no-op once versions.json exists) | |
| - name: Clean up legacy gh-pages | |
| if: github.event_name == 'push' | |
| run: | | |
| git fetch origin gh-pages:refs/remotes/origin/gh-pages 2>/dev/null || true | |
| if git show origin/gh-pages:versions.json &>/dev/null 2>&1; then | |
| echo "mike already initialized, skipping cleanup" | |
| else | |
| echo "First mike deploy — wiping legacy gh-pages for clean start" | |
| git push origin --delete gh-pages 2>/dev/null || true | |
| fi | |
| # Deploy PR preview (not shown in version selector) | |
| - name: Deploy PR preview | |
| if: >- | |
| github.event_name == 'pull_request' && | |
| github.event.pull_request.head.repo.full_name == github.repository | |
| run: uv run mike deploy "pr-${{ github.event.pull_request.number }}" --push | |
| # Tokens for pull requests from forks are read-only. Build the docs without | |
| # publishing a preview so external contributions are still validated. | |
| - name: Build fork PR documentation | |
| if: >- | |
| github.event_name == 'pull_request' && | |
| github.event.pull_request.head.repo.full_name != github.repository | |
| run: uv run mkdocs build | |
| - name: Comment PR preview link | |
| if: >- | |
| github.event_name == 'pull_request' && | |
| github.event.pull_request.head.repo.full_name == github.repository | |
| uses: actions/github-script@v9 | |
| with: | |
| script: | | |
| const previewUrl = `https://kmarchais.github.io/mmgpy/pr-${{ github.event.pull_request.number }}/`; | |
| const marker = '<!-- docs-preview -->'; | |
| const body = `${marker}\n:book: **Docs preview**: ${previewUrl}`; | |
| const { data: comments } = await github.rest.issues.listComments({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: context.issue.number, | |
| }); | |
| const existing = comments.find(c => | |
| c.user.type === 'Bot' && c.body.includes(marker) | |
| ); | |
| if (!existing) { | |
| await github.rest.issues.createComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: context.issue.number, | |
| body, | |
| }); | |
| } | |
| # Clean up previews for closed/merged PRs | |
| - name: Clean up stale PR previews | |
| if: >- | |
| github.event_name == 'pull_request' && | |
| github.event.pull_request.head.repo.full_name == github.repository | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| git fetch origin gh-pages:refs/remotes/origin/gh-pages 2>/dev/null || true | |
| VERSIONS=$(git show origin/gh-pages:versions.json 2>/dev/null || echo "[]") | |
| echo "$VERSIONS" | python3 -c " | |
| import json, subprocess, sys | |
| versions = json.load(sys.stdin) | |
| for v in versions: | |
| name = v['version'] | |
| if not name.startswith('pr-'): | |
| continue | |
| pr_num = name[3:] | |
| result = subprocess.run( | |
| ['gh', 'pr', 'view', pr_num, '--json', 'state', '--jq', '.state'], | |
| capture_output=True, text=True, | |
| ) | |
| state = result.stdout.strip() | |
| if state in ('CLOSED', 'MERGED'): | |
| print(f'Deleting preview for {name} (PR is {state})') | |
| subprocess.run(['uv', 'run', 'mike', 'delete', name, '--push']) | |
| else: | |
| print(f'Keeping {name} (PR is {state})') | |
| " | |
| # "dev" always reflects the current main branch. | |
| # Versioned release deploys live in build-wheels.yml so they're gated on | |
| # a successful PyPI upload (we never publish docs for a release whose | |
| # wheel never shipped). | |
| - name: Deploy dev docs | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| run: uv run mike deploy dev --push |