Merge pull request #5 from denisecase/dependabot/github_actions/lyche… #8
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
| # ============================================================ | |
| # .github/workflows/deploy-mkdocs.yml (Deploy MkDocs) | |
| # ============================================================ | |
| # SOURCE: https://github.com/denisecase/templates | |
| # | |
| # WHY-FILE: Build and deploy documentation to GitHub Pages on pushes to main. | |
| # REQ: Repo Settings -> Pages -> Build and deployment -> Source: | |
| # GitHub Actions | |
| name: Docs Deploy (MkDocs) | |
| on: | |
| push: | |
| branches: [main] # WHY: Run when pushing to main branch. | |
| workflow_dispatch: # WHY: Allow manual triggering from Actions tab. | |
| permissions: | |
| contents: read # WHY: Needed to checkout code. | |
| pages: write # WHY: Required to deploy to GitHub Pages. | |
| id-token: write # WHY: Required by deploy-pages for OIDC. | |
| env: | |
| PYTHONUNBUFFERED: "1" # WHY: Real-time logging. | |
| PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters. | |
| concurrency: | |
| # WHY: Only one Pages deployment at a time per branch. | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| docs: | |
| name: Deploy MkDocs documentation site | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 30 # WHY: Prevent hanging jobs. If over, it is likely stuck. | |
| steps: | |
| # ============================================================ | |
| # ASSEMBLE: Get code and set up environment | |
| # ============================================================ | |
| - name: A1) Checkout repository code | |
| # WHY: Needed to access files for checks. | |
| uses: actions/checkout@v6 | |
| - name: A2) Configure GitHub Pages | |
| # WHY: Sets Pages metadata for deployments. | |
| uses: actions/configure-pages@v5 | |
| - name: A3) Install uv (with caching) | |
| uses: astral-sh/setup-uv@v7 | |
| with: | |
| enable-cache: true | |
| - name: A4) Install Python version 3.14 | |
| run: uv python install 3.14 | |
| - name: A5) Sync to install dependencies | |
| run: uv sync --extra dev --extra docs --upgrade | |
| # ============================================================ | |
| # BASELINE CHECKS: Fail fast and validate | |
| # ============================================================ | |
| - name: B1) Fail fast if no MkDocs configuration | |
| run: | | |
| if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then | |
| echo "MkDocs configuration found. Proceeding." | |
| else | |
| echo "ERROR: mkdocs.yml not found." | |
| echo "If you do not want documentation deployment," | |
| echo "delete .github/workflows/deploy-mkdocs.yml (or add mkdocs.yml)." | |
| exit 1 | |
| fi | |
| # ============================================================ | |
| # === DEPLOY: Build and deploy === | |
| # ============================================================ | |
| - name: D1) Build docs (mkdocs --strict) | |
| run: uv run mkdocs build --strict --verbose | |
| - name: D2) Upload Pages artifact | |
| # WHY: Package the built site for Pages deployment. | |
| uses: actions/upload-pages-artifact@v4 | |
| with: | |
| path: site | |
| - name: D3) Deploy to GitHub Pages | |
| # WHY: Publish artifact to GitHub Pages. | |
| uses: actions/deploy-pages@v4 |