docs.yaml

---
name: Docs
"on":
  workflow_call:
    inputs:
      dependency-graph-output:
        description: 'Location in the repository of the dependency graph image.'
        required: false
        type: string
        default: ./docs/assets/dependencies.mmd
  push:
    branches:
      - main

# Defaults sets in workflow_call.inputs or workflow_dispatch.inputs are not propagated to other events.
# We have to manually manage them: https://github.com/orgs/community/discussions/39357#discussioncomment-7500641
env:
  dependency-graph-output: >-
    ${{ inputs.dependency-graph-output == null && './docs/assets/dependencies.mmd' || inputs.dependency-graph-output }}

concurrency:
  # Group workflow jobs so new commits cancels in-progress execution triggered by previous commits. Source:
  # https://mail.python.org/archives/list/pypa-committers@python.org/thread/PCBCQMJF64JGRBOX7E2EE4YLKHT4DI55/
  # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

jobs:

  autofix-typo:
    name: Fix typos
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: crate-ci/typos@v1.39.2
        with:
          write_changes: true
      - name: Remove local typos binary
        run: rm ./typos
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          # We need custom PAT with workflows permissions to fix typos in .github/workflows/*.yaml` files.
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Typo"
          title: "[autofix] Typo"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          labels: "📚 documentation"
          branch: autofix-typo

  project-metadata:
    name: Project metadata
    runs-on: ubuntu-24.04
    outputs:
      mailmap_exists: ${{ steps.project-metadata.outputs.mailmap_exists }}
      image_files: ${{ steps.project-metadata.outputs.image_files }}
      is_python_project: ${{ steps.project-metadata.outputs.is_python_project }}
      package_name: ${{ steps.project-metadata.outputs.package_name }}
      is_sphinx: ${{ steps.project-metadata.outputs.is_sphinx }}
      active_autodoc: ${{ steps.project-metadata.outputs.active_autodoc }}
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.4
      - name: Run gha-utils metadata
        id: project-metadata
        env:
          GITHUB_CONTEXT: ${{ toJSON(github) }}
        run: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt
          --
          gha-utils metadata --overwrite "$GITHUB_OUTPUT"

  optimize-images:
    name: Optimize images
    needs:
      - project-metadata
    if: needs.project-metadata.outputs.image_files
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: calibreapp/image-actions@1.4.1
        id: image_actions
        with:
          compressOnly: true
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Optimize images"
          title: "[autofix] Optimize images"
          body: >
            ${{ steps.image_actions.outputs.markdown }}


            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          labels: "📚 documentation"
          branch: optimize-images

  update-mailmap:
    name: Update .mailmap
    needs:
      - project-metadata
    if: fromJSON(needs.project-metadata.outputs.mailmap_exists)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
        with:
          # Fetch all history to extract all contributors.
          fetch-depth: 0
      - uses: astral-sh/setup-uv@v7.1.4
      - name: Generate .mailmap
        run: >
          uvx
          --with-requirements https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/gha-utils.txt
          --
          gha-utils mailmap-sync --skip-if-missing ./.mailmap
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Update .mailmap"
          title: "[autofix] Update `.mailmap`"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          labels: "📚 documentation"
          branch: update-mailmap

  update-deps-graph:
    name: Update dependency graph
    needs:
      - project-metadata
    if: fromJSON(needs.project-metadata.outputs.is_python_project)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.4
      - name: Install pipdeptree
        run: |
          uv --no-progress venv
          uv --no-progress pip install \
          --requirement https://raw.githubusercontent.com/kdeldycke/workflows/main/requirements/pipdeptree.txt
      - name: Install project
        run: |
          uv --no-progress pip install .
      - name: Run uv for debug
        # TODO: switch from pipdeptree to uv.
        # See: https://github.com/astral-sh/uv/issues/4439#issuecomment-2183911185
        run: |
          uv --no-progress pip tree
      - name: Run pipdeptree for debug
        run: >
          uv --no-progress run --frozen -- pipdeptree ${{ needs.project-metadata.outputs.package_name
          && format('--packages {0}', needs.project-metadata.outputs.package_name)}}
      - name: Create dir structure
        run: |
          mkdir -p "$(dirname "${{ env.dependency-graph-output }}")"
      # TODO: generate a graph for each extra requirement sets (like main, dev, docs, tests, ...).
      # See: https://github.com/tox-dev/pipdeptree/issues/107
      - name: Generate graph
        run: >
          uv --no-progress run --frozen -- pipdeptree ${{ needs.project-metadata.outputs.package_name
          && format('--packages {0}', needs.project-metadata.outputs.package_name)}}
          --output mermaid > "${{ env.dependency-graph-output }}"
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Regenerate dependency graph"
          title: "[autofix] Regenerate dependency graph"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          labels: "📚 documentation"
          branch: update-deps-graph

  update-autodoc:
    name: Update autodoc
    needs:
      - project-metadata
    if: >
      fromJSON(needs.project-metadata.outputs.is_python_project)
      && fromJSON(needs.project-metadata.outputs.active_autodoc)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.4
      - name: Run Sphinx
        run: |
          uv --no-progress run --frozen --extra docs -- sphinx-apidoc --no-toc --module-first --force -o ./docs .
      - uses: peter-evans/create-pull-request@v7.0.8
        with:
          assignees: ${{ github.actor }}
          commit-message: "[autofix] Update Sphinx autodoc"
          title: "[autofix] Update Sphinx autodoc"
          body: >
            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          labels: "📚 documentation"
          branch: update-autodoc

  deploy-docs:
    name: Deploy Sphinx doc
    needs:
      - project-metadata
    if: fromJSON(needs.project-metadata.outputs.is_python_project) && fromJSON(needs.project-metadata.outputs.is_sphinx)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5.0.1
      - uses: astral-sh/setup-uv@v7.1.4
        with:
          # We rely on recent Python features in some of our {click:run} directives.
          python-version: "3.14"
      - name: Install Graphviz
        # So we can use the sphinx.ext.graphviz plugin.
        # See: https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
        run: |
          sudo apt update
          sudo apt install --yes graphviz
      - name: Build documentation
        run: |
          uv --no-progress run --frozen --all-extras -- sphinx-build -b html ./docs ./docs/html
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/html
          force_orphan: true

  awesome-template-sync:
    name: Sync awesome template
    if: >
      startsWith(github.event.repository.name, 'awesome-')
      && github.event.repository.name != 'awesome-template'
    runs-on: ubuntu-24.04
    # We need custom PAT through the whole job so we get workflow permissions to update all the boilerplate .github
    # files from awesome-template.
    steps:
      - name: Initial checkout
        uses: actions/checkout@v5.0.1
        with:
          token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          fetch-depth: 0
      - name: Sync from template repo
        id: template_sync
        uses: AndreasAugustin/actions-template-sync@v2.5.2
        with:
          github_token: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT || secrets.GITHUB_TOKEN }}
          source_repo_path: kdeldycke/awesome-template
          # Action will update PR only if there is file changes. is_force_push_pr also force the PR to be updated
          # only if metadata changes.
          is_force_push_pr: true
          is_allow_hooks: true
          is_pr_cleanup: true
          # Replace "/kdeldycke/awesome-template/" in URLs by "/kdeldycke/awesome-<repo_id>/".
          hooks: >
            precommit:
              commands:
                - find ./.github/ -type f -iregex ".*\.\(md\|yaml\)$" -print -exec sed -i
                  "s/\/kdeldycke\/awesome-template\//\/kdeldycke\/${{ github.event.repository.name }}\//g" "{}" \;
          pr_title: "[sync] Updates from `awesome-template`"
          pr_commit_msg: "[sync] Updates from awesome-template"
          pr_branch_name_prefix: "sync-awesome-template"
          pr_body: >
            Files synced from [`kdeldycke/awesome-template@${TEMPLATE_GIT_HASH}`
            repository](${SOURCE_REPO}/tree/${TEMPLATE_GIT_HASH}).


            <details><summary><code>Workflow metadata</code></summary>


            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
            }}/blob/${{ github.sha }}/.github/workflows/docs.yaml) workflow.


            </details>
          pr_labels: "📚 documentation"