python-package-mkdocs-gh-deploy.yml

---
name: Build and deployment of MkDocs documentation
on:
  workflow_call:
    inputs:
      package-path:
        required: false
        type: string
        description: Path to a Python package or project
        default: .
      python-version:
        required: false
        type: string
        description: Python version to use (not applicable if uv.lock is present)
        default: 3.x
      uv-version:
        required: false
        type: string
        description: Version of uv to use (applicable only if uv.lock is present)
        default: latest
      mkdocs-config-file:
        required: false
        type: string
        description: MkDocs config file
        default: mkdocs.yml
      mkdocs-strict:
        required: false
        type: boolean
        description: Enable strict mode for MkDocs build
        default: true
      mkdocs-theme:
        required: false
        type: string
        description: Theme to use for MkDocs (mkdocs or readthedocs)
        default: mkdocs
      runs-on:
        required: false
        type: string
        description: GitHub Actions runner to use
        default: ubuntu-latest
    secrets:
      GH_TOKEN:
        required: false
        description: GitHub token
  workflow_dispatch:  # checkov:skip=CKV_GHA_7:workflow_dispatch inputs are required for MkDocs build settings
    inputs:
      package-path:
        required: false
        type: string
        description: Path to a Python package or project
        default: .
      python-version:
        required: false
        type: string
        description: Python version to use (not applicable if uv.lock is present)
        default: 3.x
      uv-version:
        required: false
        type: string
        description: Version of uv to use (applicable only if uv.lock is present)
        default: latest
      mkdocs-config-file:
        required: false
        type: string
        description: MkDocs config file
        default: mkdocs.yml
      mkdocs-strict:
        required: false
        type: boolean
        description: Enable strict mode for MkDocs build
        default: true
      mkdocs-theme:
        required: false
        type: string
        description: Theme to use for MkDocs (mkdocs or readthedocs)
        default: mkdocs
      runs-on:
        required: false
        type: string
        description: GitHub Actions runner to use
        default: ubuntu-latest
permissions:
  contents: write
defaults:
  run:
    shell: bash -euo pipefail {0}
    working-directory: .
jobs:
  build-and-deploy:
    runs-on: ${{ inputs.runs-on }}
    env:
      MKDOCS_SITE_DIR: ${{ inputs.package-path }}/site
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          fetch-depth: 1
          persist-credentials: false
      - name: Detect uv.lock or poetry.lock
        working-directory: ${{ inputs.package-path }}
        run: |
          if [[ -f uv.lock ]]; then
            echo "LOCK_FILE=uv.lock" >> "${GITHUB_ENV}"
          elif [[ -f poetry.lock ]]; then
            echo "LOCK_FILE=poetry.lock" >> "${GITHUB_ENV}"
          else
            echo "LOCK_FILE=" >> "${GITHUB_ENV}"
          fi
      - name: Set up uv
        if: env.LOCK_FILE == 'uv.lock'
        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
        with:
          version: ${{ inputs.uv-version }}
      - name: Install packages using uv
        if: env.LOCK_FILE == 'uv.lock'
        working-directory: ${{ inputs.package-path }}
        run: |
          uv sync --all-groups
          tee -a "${GITHUB_ENV}" <<< "EXECUTOR=uv run --directory ${PWD}"
      - name: Set up Python
        if: env.LOCK_FILE != 'uv.lock'
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
        with:
          python-version: ${{ inputs.python-version }}
      - name: Install packages
        if: env.LOCK_FILE != 'uv.lock'
        working-directory: ${{ inputs.package-path }}
        run: |
          pip install -U --no-cache-dir pip
          if [[ "${LOCK_FILE}" == "poetry.lock" ]]; then
            pip install --no-cache-dir poetry
            poetry lock --no-interaction
            poetry install --no-interaction --no-root
            tee -a "${GITHUB_ENV}" <<< "EXECUTOR=poetry run -C ${PWD}"
          else
            pip install -U --no-cache-dir mkdocs
            tee -a "${GITHUB_ENV}" <<< "EXECUTOR="
          fi
      - name: Build MkDocs site
        working-directory: ${{ inputs.package-path }}
        env:
          MKDOCS_CONFIG_FILE: ${{ inputs.mkdocs-config-file }}
          MKDOCS_STRICT: ${{ inputs.mkdocs-strict && 'true' || null }}
          MKDOCS_THEME: ${{ inputs.mkdocs-theme }}
        run: | # zizmor: ignore[template-injection]
          args=(
            ${MKDOCS_CONFIG_FILE:+--config-file="${MKDOCS_CONFIG_FILE}"}
            ${MKDOCS_STRICT:+--strict}
            ${MKDOCS_THEME:+--theme="${MKDOCS_THEME}"}
          )
          ${{ env.EXECUTOR }} mkdocs build --clean --site-dir="${MKDOCS_SITE_DIR}" "${args[@]:-}"
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e  # v4.0.0
        with:
          github_token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}  # zizmor: ignore[secrets-outside-env] caller-provided secret
          publish_dir: ${{ env.MKDOCS_SITE_DIR }}