mkdocs-publish.yml

name: Publish MkDocs Documentation

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy (e.g. 20.0)'
        required: true
        default: '20.0'
        type: string

permissions:
  contents: write
  pages: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
      with:
        submodules: recursive
        fetch-depth: 0  # Required for mike to work properly
    
    - name: Update Assets
      run: git submodule update --remote --recursive documentation-assets

    - 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 \
          mike \
          mkdocs-material \
          mkdocs-macros-plugin \
          mkdocs-monorepo-plugin \
          mkdocs-site-urls \
          mkdocs-caption \
          markdown-tables-extended \
          mkdocs-minify-plugin

    - 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: |
        # Create backup
        cp mkdocs.yml mkdocs.yml.bak
        # Substitute variables
        envsubst '$BUILD_DATE $GIT_INFO $CURRENT_YEAR' < mkdocs.yml.bak > mkdocs.yml
        # Display substituted content for debugging
        echo "--- Checking substituted content ---"
        cat mkdocs.yml | grep -A5 copyright

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

    - name: Deploy documentation
      run: |
        mike deploy --push ${{ inputs.version }}
    
    - name: Copy Jenkins files to gh-pages
      run: |
        # Discard local changes to mkdocs.yml before switching branches
        git checkout -- mkdocs.yml
        
        # Checkout gh-pages branch
        git checkout gh-pages
        
        # Copy Jenkins files from the source branch
        git checkout ${{ github.sha }} -- tools/jenkins/Jenkinsfile tools/jenkins/service.yml tools/jenkins/.rsync-exclude tools/jenkins/get_svn_docbin
        
        # Move them to root of gh-pages and update staging
        mv tools/jenkins/Jenkinsfile .
        mv tools/jenkins/service.yml .
        mv tools/jenkins/.rsync-exclude .
        mv tools/jenkins/get_svn_docbin .
        
        # Remove from staging in old location and add to staging in new location
        git rm -r tools
        git add Jenkinsfile service.yml .rsync-exclude get_svn_docbin
        
        # Commit if there are changes
        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