name: Docs

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      deploy:
        description: "Force deploy to GitHub Pages"
        type: boolean
        default: false
  push:
    branches-ignore: [master]

permissions:
  contents: write

# Shared with doctests.yml's publish job so the two never push gh-pages at once.
concurrency:
  group: gh-pages-publish
  cancel-in-progress: false

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Decide whether to publish
        id: gate
        shell: bash
        run: |
          if [ "${{ github.event_name }}" = "release" ] || \
             { [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.deploy }}" = "true" ]; }; then
            echo "publish=true" >> "$GITHUB_OUTPUT"
          else
            echo "publish=false" >> "$GITHUB_OUTPUT"
          fi

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Nix
        if: steps.gate.outputs.publish == 'true'
        uses: DeterminateSystems/nix-installer-action@main

      - name: Setup Cachix
        if: steps.gate.outputs.publish == 'true'
        uses: cachix/cachix-action@v15
        with:
          name: logos-co
          authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"

      - name: Install Doxygen
        run: sudo apt-get install -y doxygen

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

      - name: Install Python dependencies
        run: pip install -r docs/requirements.txt

      - name: Run Doxygen
        run: doxygen ./docs/Doxyfile

      # conf.py derives the version from the latest git tag, so this build is
      # already stamped with the release being published.
      - name: Build Sphinx HTML
        run: make html
        working-directory: docs

      - name: Upload preview artifact
        if: github.event_name == 'push'
        uses: actions/upload-artifact@v4
        with:
          name: docs-preview
          path: docs/_build/html
          retention-days: 7

      - name: Resolve release tag
        id: ver
        if: steps.gate.outputs.publish == 'true'
        shell: bash
        run: echo "tag=$(git describe --tags --abbrev=0)" >> "$GITHUB_OUTPUT"

      - name: Publish this version
        if: steps.gate.outputs.publish == 'true'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html
          destination_dir: ${{ steps.ver.outputs.tag }}
          keep_files: true

      - name: Publish this version as latest
        if: steps.gate.outputs.publish == 'true'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html
          destination_dir: latest
          keep_files: true

      - name: Publish root files
        if: steps.gate.outputs.publish == 'true'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_root
          destination_dir: .
          keep_files: true