build-docs.yml

name: Build docs

on:
  workflow_dispatch:
  release:
    types:
      - published

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          lfs: true
          fetch-depth: 0
      - uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
        with:
          version: "latest"
      - name: setup python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
        with:
          python-version: "3.10"

      - name: Install quarto
        uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0

      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
      - name: Build MkDocs documentation
        run: |
          uv venv
          . .venv/bin/activate
          uv sync --group docs
          just docs-build --clean
        working-directory: .

      - name: Publish docs to GH Pages
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # Documentation versioning was removed: publish the freshly built site at
          # the gh-pages root. A separate worktree keeps the build output untouched.
          # Existing gh-pages content (e.g. archived version directories, CNAME,
          # .nojekyll) is left in place — only the root documentation is refreshed.
          git worktree add gh-pages-publish gh-pages
          rsync -a ./site/ gh-pages-publish/

          cd gh-pages-publish
          git add -A
          git commit -m "docs: deploy docs" || echo "No documentation changes to deploy"
          git push origin gh-pages