docs(jss): sync validation audit counts #103
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: Docs (MkDocs) | |
| # Build the MkDocs Material site and publish it to GitHub Pages. | |
| # | |
| # - pull_request : build with ``--strict`` only (no deploy). This is a | |
| # documentation quality gate — a broken intra-doc link, a missing nav | |
| # page, or a mkdocstrings failure reds the PR instead of silently | |
| # shipping a broken site. | |
| # - push to main : build ``--strict`` and deploy to Pages. | |
| # | |
| # Deployment uses the official GitHub Pages actions (artifact upload + | |
| # deploy-pages), so no ``gh-pages`` branch is created or force-pushed. The | |
| # repository must have Pages enabled with the source set to "GitHub Actions" | |
| # (Settings -> Pages -> Build and deployment -> Source: GitHub Actions); the | |
| # build job runs regardless, so the strict-build check works even before | |
| # Pages is switched on. | |
| on: | |
| push: | |
| branches: [ main ] | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - 'src/statspai/**' # API reference is generated from docstrings | |
| - 'scripts/gen_api_ref.py' | |
| - '.github/workflows/docs.yml' | |
| pull_request: | |
| branches: [ main ] | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - 'scripts/gen_api_ref.py' | |
| - '.github/workflows/docs.yml' | |
| workflow_dispatch: | |
| # Opt JavaScript actions into the Node 24 runtime ahead of GitHub's hard | |
| # cutover — same posture as ci-cd.yml. | |
| env: | |
| FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true' | |
| # Allow only one concurrent deployment; let in-progress runs finish so a | |
| # half-published site is never left live. | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v5 | |
| - name: Set up Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: '3.11' | |
| - name: Install docs toolchain | |
| # mkdocstrings renders the API reference from the package docstrings, | |
| # so the package itself must be importable; ``.[docs]`` pulls the | |
| # MkDocs Material + mkdocstrings + gen-files + literate-nav stack. | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -e ".[docs]" | |
| - name: Build site (strict) | |
| run: mkdocs build --strict --site-dir _site | |
| - name: Upload Pages artifact | |
| if: github.event_name != 'pull_request' | |
| uses: actions/upload-pages-artifact@v5 | |
| with: | |
| path: _site | |
| deploy: | |
| # Publish only from main; PRs stop at the strict-build check above. | |
| if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| permissions: | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v5 |