📖 Deploy MKDocs Documentation (branch: main) #54
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: 📖 Deploy MKDocs Documentation | |
| run-name: "📖 Deploy MKDocs Documentation (branch: ${{ github.ref_name }})" | |
| on: | |
| push: | |
| branches: | |
| - main | |
| paths: | |
| - 'docs/**' | |
| - 'pyproject.toml' | |
| - '.github/workflows/docs.yml' | |
| workflow_dispatch: | |
| # Permissions for GitHub Actions deployment | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Setup Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' | |
| - name: Install uv | |
| uses: astral-sh/setup-uv@v4 | |
| with: | |
| version: "latest" | |
| - name: Install docs dependencies (from pyproject extras) | |
| run: | | |
| # Extract docs dependencies from pyproject.toml | |
| python - <<'PY' | |
| import pathlib | |
| import tomllib | |
| data = tomllib.loads(pathlib.Path('pyproject.toml').read_text(encoding='utf-8')) | |
| docs_deps = ( | |
| data.get('project', {}) | |
| .get('optional-dependencies', {}) | |
| .get('docs', []) | |
| ) | |
| if not docs_deps: | |
| raise SystemExit('No [project.optional-dependencies].docs found in pyproject.toml') | |
| req = pathlib.Path('requirements-docs.txt') | |
| req.write_text('\n'.join(docs_deps) + '\n', encoding='utf-8') | |
| print(f'Wrote {req} with {len(docs_deps)} dependencies') | |
| PY | |
| # Install into system Python (--system required for uv outside a venv) | |
| uv pip install --system -r requirements-docs.txt | |
| - name: Setup Pages | |
| id: pages | |
| uses: actions/configure-pages@v5 | |
| - name: Build documentation | |
| run: | | |
| # Build without --strict to allow warnings (broken anchors are documentation debt, not blockers) | |
| mkdocs build --clean -f docs/mkdocs.yml | |
| touch ./site/.nojekyll | |
| env: | |
| AZURE_SPEECH_KEY: "dummy-key-for-docs" | |
| AZURE_SPEECH_REGION: "eastus" | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: ./site | |
| deploy: | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| permissions: | |
| pages: write | |
| id-token: write | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |