docs.yml

name: docs

permissions: 
  contents: write

on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
        with:
          # Fetch all history for applying timestamps to every page
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@7f4fc3e22c37d6ff65e88745f38bd3157c663f7c # v4.9.1
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Upgrade Python packaging tools
        run: pip install --disable-pip-version-check --upgrade pip setuptools wheel

      - name: Install tox
        run: pip install tox

      - name: set SPHINX_VERSION
        run: |
          tox -edocs --notest
          echo "SPHINX_VERSION=$(.tox/docs/bin/python -c "import importlib.metadata;print(importlib.metadata.version('sphinx'))")" >> $GITHUB_ENV

      - name: Cache sphinx
        uses: actions/cache@6f8efc29b200d32929f49075959781ed54ec270c # v3.5.0
        with:
          path: docs/.sphinx
          key: sphinx-${{ env.SPHINX_VERSION }}-${{ hashFiles('.generator/schemas/**/openapi.yaml') }}
          restore-keys: sphinx-${{ env.SPHINX_VERSION }}

      - name: Build documentation
        run: tox -e docs

      - name: Compress site
        run: tar czf site.tar.gz site

      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: documentation
          path: site.tar.gz

  publish:
    runs-on: ubuntu-latest

    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
    needs:
      - build

    steps:
      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: documentation
          path: site

      - name: Uncompress site
        run: tar xzf site/site.tar.gz && rm site/site.tar.gz

      - uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          commit_message: ${{ github.event.head_commit.message }}
          # Write .nojekyll at the root, see:
          # https://help.github.com/en/github/working-with-github-pages/about-github-pages#static-site-generators
          enable_jekyll: false
          # Only deploy if there were changes
          allow_empty_commit: false
          # GH pages branch is getting super big, so we want to reduce it by creating an orphan branch
          force_orphan: true