docs.yml

name: docs

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: install mdBook
        run: |
          mkdir -p "$HOME/.local/bin"
          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz \
            | tar -xz -C "$HOME/.local/bin"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: generate chapters from the repository's own files
        run: python docs-site/build.py

      - name: the generated chapters must match what is committed
        # The site has no content of its own. If this fails, a source file
        # changed without the site being regenerated, and the two have drifted.
        run: git diff --exit-code docs-site/src

      - run: mdbook build docs-site

      # The book is served from two addresses from this one build, so every
      # page needs a canonical link naming agenticdatasets.org. mdBook cannot
      # emit these (head.hbs sees `index.md`, not `index.html`), so it happens
      # here -- and the --check run is what stops this step being quietly
      # dropped, since a missing tag is invisible in the rendered page.
      - name: canonical links
        run: |
          python docs-site/postbuild.py
          python docs-site/postbuild.py --check

      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs-site/book

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4