Merge branch 'features/consolidate-markdown-docs' #9
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: [ master ] | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - '.github/workflows/docs.yml' | |
| pull_request: | |
| branches: [ master ] | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - '.github/workflows/docs.yml' | |
| release: | |
| types: [published] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| pull-requests: write | |
| # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # Fetch all history for git info plugin | |
| - name: Setup Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' | |
| - name: Setup uv | |
| uses: astral-sh/setup-uv@v4 | |
| with: | |
| enable-cache: true | |
| - name: Install dependencies | |
| run: | | |
| uv sync --extra docs | |
| - name: Configure git for MkDocs | |
| run: | | |
| git config user.name github-actions | |
| git config user.email [email protected] | |
| - name: Build documentation | |
| run: | | |
| source .venv/bin/activate | |
| mkdocs build --strict | |
| - name: Upload documentation artifacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: documentation-site | |
| path: site/ | |
| # Deploy to GitHub Pages on push to master or release | |
| deploy: | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/master' || github.event_name == 'release' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Download documentation artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: documentation-site | |
| path: site/ | |
| - name: Upload to GitHub Pages | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site/ | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| # Comment on PRs with preview link | |
| pr-comment: | |
| if: github.event_name == 'pull_request' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Download documentation artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: documentation-site | |
| path: site/ | |
| - name: Comment PR with preview info | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const { owner, repo, number } = context.issue; | |
| const body = ` | |
| ## 📚 Documentation Preview | |
| The documentation has been built successfully for this PR. | |
| **Changes detected in:** | |
| - Documentation files (\`docs/\`) | |
| - MkDocs configuration (\`mkdocs.yml\`) | |
| **Build status:** ✅ Success | |
| The documentation will be automatically deployed to GitHub Pages when this PR is merged to master. | |
| --- | |
| <sub>Generated by docs workflow</sub> | |
| `; | |
| // Check if we already commented | |
| const comments = await github.rest.issues.listComments({ | |
| owner, | |
| repo, | |
| issue_number: number, | |
| }); | |
| const existingComment = comments.data.find(comment => | |
| comment.user.login === 'github-actions[bot]' && | |
| comment.body.includes('📚 Documentation Preview') | |
| ); | |
| if (existingComment) { | |
| await github.rest.issues.updateComment({ | |
| owner, | |
| repo, | |
| comment_id: existingComment.id, | |
| body | |
| }); | |
| } else { | |
| await github.rest.issues.createComment({ | |
| owner, | |
| repo, | |
| issue_number: number, | |
| body | |
| }); | |
| } |