docs.yml

# Builds docs/ with MkDocs Material and publishes it to GitHub Pages.
# Enable it once under Settings → Pages → Build and deployment → Source: GitHub Actions.
name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.github/workflows/docs.yml'
  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'
      # No pip cache: setup-python's cache needs a requirements file to hash, and
      # this is a Node repository with none.
      - run: pip install 'mkdocs-material==9.*'
      - run: mkdocs build --strict

      # RexDB's page, published under /rexdb/. There is one Pages site per repository and this is it, so the
      # database branch deploys nothing of its own; it only lends the three files its page is made of. The page
      # reads the branch directly, so nothing here has to rebuild when somebody contributes a disc.
      - name: Add the RexDB page
        run: |
          git fetch --depth 1 origin RexDB
          mkdir -p site/rexdb
          git archive FETCH_HEAD index.html app.js style.css | tar -x -C site/rexdb
          test -s site/rexdb/index.html

      - uses: actions/upload-pages-artifact@v3
        with:
          path: site

  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