documentation.yml

# file: .github/workflows/documentation.yml
# version: 1.1.2
# guid: docs-automation-workflow-2025

name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - '**/*.md'
      - '.github/workflows/documentation.yml'
  pull_request:
    paths:
      - 'docs/**'
      - '**/*.md'
      - '.github/workflows/documentation.yml'
  schedule:
    - cron: '0 5 * * 1'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build-docs:
    name: Build Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          submodules: recursive
      - name: Generate helper documentation
        uses: falkcorp/gha-docs-generator@ecaefb4b0110d11683bc7ad0b6b968209aeca4af # v1.1.6-rc.4
        with:
          source-dir: .github/workflows/scripts
          workflows-dir: .github/workflows
          output-dir: docs/generated

      - name: Detect documentation toolchain
        id: detect
        shell: bash
        run: |
          set -euo pipefail
          tool="none"
          if [ -f "mkdocs.yml" ] || [ -f "mkdocs.yaml" ]; then
            tool="mkdocs"
          elif [ -f "docs/conf.py" ]; then
            tool="sphinx"
          elif [ -f "package.json" ] && jq -e '.scripts.buildDocs' package.json >/dev/null 2>&1; then
            tool="npm"
          fi
          echo "tool=${tool}" >> "$GITHUB_OUTPUT"
          echo "Detected documentation tool: ${tool}"

      - name: Build with MkDocs
        if: steps.detect.outputs.tool == 'mkdocs'
        run: |
          pip install --upgrade pip
          pip install mkdocs mkdocs-material
          mkdocs build --strict --site-dir site

      - name: Build with Sphinx
        if: steps.detect.outputs.tool == 'sphinx'
        run: |
          python -m pip install --upgrade pip
          python -m pip install sphinx sphinx-autobuild sphinx-rtd-theme
          sphinx-build -b html docs/ _build/html

      - name: Build with npm script
        if: steps.detect.outputs.tool == 'npm'
        run: |
          npm ci || npm install
          npm run buildDocs

      - name: Validate Markdown links
        run: |
          pip install --upgrade pip
          pip install linkchecker
          if find . -name "*.md" | head -1 | grep -q .; then
            linkchecker --ignore-url "mailto:" --ignore-url "http://localhost" docs || true
          else
            echo "No Markdown files detected in docs/."
          fi

      - name: Upload documentation artifact
        id: upload
        if: steps.detect.outputs.tool != 'none'
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: documentation-build
          path: |
            site
            _build/html
          if-no-files-found: ignore

  deploy-docs:
    name: Deploy Documentation
    needs: build-docs
    if: needs.build-docs.result == 'success' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: documentation
    env:
      DOCS_DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: Check deployment token
        if: env.DOCS_DEPLOY_TOKEN == ''
        run: |
          echo "DOCS_DEPLOY_TOKEN secret not set; skipping deployment."
          exit 0

      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          submodules: recursive
        if: env.DOCS_DEPLOY_TOKEN != ''

      - name: Download documentation artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        if: env.DOCS_DEPLOY_TOKEN != ''
        continue-on-error: true
        with:
          name: documentation-build
          path: docs-build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
        if: env.DOCS_DEPLOY_TOKEN != '' && hashFiles('docs-build/**') != ''
        with:
          github_token: ${{ env.DOCS_DEPLOY_TOKEN }}
          publish_dir: docs-build/site
          keep_files: true