mkdocs-publish.yml

name: Publish MkDocs Documentation

on:
  workflow_dispatch:
    inputs:
      version_override:
        description: 'Version override (leave empty to use mkdocs.yml value)'
        required: false
        default: ''
        type: string
      set_as_latest:
        description: 'Set this version as the default/latest'
        required: false
        default: false
        type: boolean
  workflow_call:
    inputs:
      version_override:
        type: string
        default: ''
      set_as_latest:
        type: boolean
        default: false

permissions:
  contents: write
  pages: write

# Prevent concurrent mike pushes to gh-pages (e.g., v20.0 and main publishing simultaneously)
concurrency:
  group: docs-publish
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: recursive
        fetch-depth: 0

    - name: Update Assets
      run: git submodule update --remote --recursive documentation-assets

    - name: Install yq
      run: |
        sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.44.1/yq_linux_amd64
        sudo chmod +x /usr/local/bin/yq

    - name: Determine Version
      id: version
      run: |
        if [ -n "${{ inputs.version_override }}" ]; then
          VERSION="${{ inputs.version_override }}"
          echo "Using override version: ${VERSION}"
        else
          # Use -r for raw output (no quotes) and ensure string format
          VERSION=$(yq -r '.extra.version_majmin | tostring' mkdocs.yml)
          # Validate version format (X.Y)
          if ! echo "${VERSION}" | grep -qE '^[0-9]+\.[0-9]+$'; then
            echo "ERROR: Invalid version format '${VERSION}'. Expected X.Y (e.g., 20.0, 21.0)"
            exit 1
          fi
          echo "Using mkdocs.yml version: ${VERSION}"
        fi
        echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'

    - name: Set up Git
      run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "github-actions[bot]@users.noreply.github.com"

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r tools/requirements-docs.txt

    - name: Get Git Info
      id: git-info
      run: |
        BRANCH=$(git rev-parse --abbrev-ref HEAD)
        HASH=$(git rev-parse --short HEAD)
        echo "GIT_INFO=${BRANCH}:${HASH}" >> $GITHUB_OUTPUT
        echo "DATE=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
        echo "CURRENT_YEAR=$(date +'%Y')" >> $GITHUB_OUTPUT

    - name: Substitute env variables in mkdocs.yml
      env:
        GIT_INFO: ${{ steps.git-info.outputs.GIT_INFO }}
        BUILD_DATE: ${{ steps.git-info.outputs.DATE }}
        CURRENT_YEAR: ${{ steps.git-info.outputs.CURRENT_YEAR }}
      run: |
        cp mkdocs.yml mkdocs.yml.bak
        envsubst '$BUILD_DATE $GIT_INFO $CURRENT_YEAR' < mkdocs.yml.bak > mkdocs.yml
        echo "--- Checking substituted content ---"
        cat mkdocs.yml | grep -A5 copyright

    - name: Move Styles into docs
      run: |
        mv documentation-assets docs

    - name: Deploy documentation
      run: |
        VERSION="${{ steps.version.outputs.VERSION }}"
        if [ "${{ inputs.set_as_latest }}" = "true" ]; then
          mike deploy --push --update-aliases ${VERSION} latest
          mike set-default --push latest
        else
          mike deploy --push ${VERSION}
        fi

    - name: Copy Jenkins files to gh-pages
      run: |
        # Always take Jenkins/deployment files from main, regardless of
        # which branch triggered this workflow. This prevents the v20.0
        # branch from overwriting PRODUCTION_VERSIONS or helper functions.
        git fetch origin main
        git checkout -- mkdocs.yml
        git checkout gh-pages
        git checkout origin/main -- tools/jenkins/Jenkinsfile tools/jenkins/service.yml tools/jenkins/.rsync-exclude tools/jenkins/get_svn_docbin
        mv tools/jenkins/Jenkinsfile .
        mv tools/jenkins/service.yml .
        mv tools/jenkins/.rsync-exclude .
        mv tools/jenkins/get_svn_docbin .
        git rm -r tools 2>/dev/null || true
        git add Jenkinsfile service.yml .rsync-exclude get_svn_docbin
        if git diff --staged --quiet; then
          echo "No changes to Jenkins files"
        else
          git commit -m "Update Jenkins deployment files"
          git push origin gh-pages
        fi