deploy-docs.yml

name: Deploy Documentation

# The published site is built from `develop`, which is the branch every fix PR
# lands on. That is deliberate: a documentation-only change reaches the site as
# soon as its PR is squashed, with no release, tag, or changelog entry needed.
#
# `main` still receives `docs/` through the normal release merge, so README,
# CONTRIBUTING, and the in-product links that point at `docs/` on the default
# branch keep resolving.
#
# IMPORTANT: this file must exist on the DEFAULT branch, not only on `develop`.
# GitHub Actions resolves workflows for non-`push` events (such as `release`)
# from the default branch only. While this file lived exclusively on the orphan
# `docs` branch, the `release` trigger below was inert and never fired, so the
# published site kept serving stale release metadata until someone ran the
# workflow by hand.
#
# Keeping a copy on the default branch does NOT cause duplicate runs. For `push`
# events GitHub uses the workflow file from the pushed commit, and the `push`
# trigger below only matches `develop`. Every job checks out `develop`
# explicitly, so the site content is always built from that branch regardless of
# which ref started the run.

on:
  push:
    branches:
      - develop
    # Only rebuild when something that affects the rendered site changes.
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'main.py'
      - 'requirements-docs.txt'
      - 'overrides/**'
      - '.github/workflows/deploy-docs.yml'

  # Rebuild when a release or pre-release is published, since the home page
  # shows release metadata baked at build time.
  release:
    types:
      - published
      - released
      - prereleased

  # Allow triggering a rebuild manually from the Actions UI.
  workflow_dispatch:

# Let a newer commit supersede an in-flight build instead of racing it to the
# gh-pages branch.
concurrency:
  group: deploy-docs
  cancel-in-progress: true

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: develop

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.11

      - name: Install MkDocs and dependencies
        run: pip install -r requirements-docs.txt

      - name: Build the site
        run: mkdocs build --strict

      - name: Deploy to GitHub Pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: mkdocs gh-deploy --force --clean --remote-branch gh-pages