api-docs.yml

# Trigger this workflow manually while choosing a tag in order update the API docs.
#
# This is going to:
# - Build the API docs
# - Deploy to GH pages
#
# The target folder for deploying docs in GH pages is:
# - If it is a devrelease tag: The tag itself.
# - Otherwise: The major version, as in the Python project metadata.
#
# If the `latest` option is selected, the docs are also deployed to the latest folder.
#
# Tip: If you need to update the docs for a certain major version without making a new release, just create
# a new tag manually while adding a "-n" suffix to the previous tag (e.g.: x.y.z-1, x.y.z-2, etc).
#

name: "API Docs"

on:
  workflow_dispatch:
    inputs:
      latest:
        type: boolean
        default: false
        required: false
        description: Latest

env:
  DEVRELEASE_PATTERN: ^\d+\.\d+\.\d+-dev\d+$  # Match any tags like '1.2.3-dev123'

jobs:
  api-docs:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version-file: .python-version

    - name: Set up uv
      run: curl -LsSf https://astral.sh/uv/install.sh | sh

    - name: Cache UV
      uses: actions/cache@v3
      with:
        path: /tmp/.uv-cache
        key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
        restore-keys: |
          uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
          uv-${{ runner.os }}

    - name: Install project
      run: make install-project

    - name: Render API docs
      run: make api-docs

    - name: Get docs version
      id: get-docs-version
      run: |
        if ! [[ -z $(echo "${GITHUB_REF#refs/tags/}" | grep -xP '${{ env.DEVRELEASE_PATTERN }}') ]] ; then
          echo "value=v${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
        else
          echo "value=v$(uvx --from commitizen cz version -p | grep -oP '^\d+')" >> $GITHUB_OUTPUT
        fi

    - name: Publish API docs to GitHub Pages
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        folder: docs/api/_build/html
        target-folder: docs/api/${{ steps.get-docs-version.outputs.value }}

    - name: Publish API docs to GitHub Pages (latest)
      if: ${{ github.event.inputs.latest != 'false' }}
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        folder: docs/api/_build/html
        target-folder: docs/api/latest