docs.yml

name: Docs

on:
  pull_request:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  FORCE_COLOR: 3

permissions: {}

jobs:
  build:
    name: documentation-build
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false
          fetch-depth: 0
          submodules: "recursive"

      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
        id: setup-go
        with:
          go-version: "1.26.1"
          cache: false
          check-latest: true

      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: 3.14

      - name: Restore Hugo builder cache
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: ./hugo_cache/
          key: ubuntu-latest-hugo-${{ steps.setup-go.outputs.go-version }}

      - name: Install Python dependencies
        run: pip install nox

      - name: Build documentation website
        run: nox -s docs

      - name: Upload documentation as artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: docs
          path: docs/public/

  deploy:
    name: documentation-deploy
    runs-on: ubuntu-latest
    needs: [build]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    permissions:
      contents: write # Required for pushing to gh-pages branch
    steps:
      - name: Download documentation artifact
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: docs
          path: docs/public/

      - name: Deploy documentation website
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/public/
          publish_branch: gh-pages
          keep_files: false
          force_orphan: true