docs.yaml

name: "docs"

on:
  push:
    tags-ignore: [ "**" ]
    branches: [ "**" ]
  pull_request:
  release:
    types: [ "released" ]

concurrency:
  group: "${{ github.workflow }}-${{ github.event.number || github.ref }}"
  cancel-in-progress: true

jobs:
  build:
    runs-on: "ubuntu-latest"
    outputs:
      branch_match: "${{ steps.setup.outputs.publishing_branch }}"
    steps:
      - name: "setup"
        id: "setup"
        uses: "KyoriPowered/ci-cookbook/actions/setup-python-env@f3b9a3fbb31e9f4320d855e7be17b028522e87be" # 2026.02.07
        with:
          activate_venv: true
      - name: "setup / install deps"
        run: "poetry install --with=docs"
      - uses: "ammaraskar/sphinx-problem-matcher@master"
      - name: "build"
        working-directory: "docs/"
        env:
          SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: "make dirhtml"
      - name: "publish / upload artifact"
        uses: "actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b" # v4.0.0
        with:
          path: "docs/_build/dirhtml/"
  deploy:
    runs-on: "ubuntu-latest"
    needs: "build"
    if: "${{ github.event_name == 'release' || (github.event_name == 'push' && needs.build.outputs.branch_match != '') }}"
    permissions:
      pages: "write"
      id-token: "write"
    environment:
      name: "github-pages"
      url: "${{ steps.deployment.outputs.page_url }}"
    steps:
      - name: "deploy / pages"
        id: "deployment"
        uses: "actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e" # v4.0.5