docs.yml

name: Docs Update
on:
  push:
    branches:
      - master
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - '.mike.yml'
      - 'README.md'
      - 'CODE_OF_CONDUCT.md'
      - 'CONTRIBUTING.md'
      - 'LICENSE'
      - 'SECURITY.md'
      - 'CHANGELOG.md'
      - 'AGENTS.md'
      - 'CLAUDE.md'
      - '**/SKILL.md'
    tags:
      - 'v*'
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v7
        with:
          python-version: '3.14'

      - name: Install dependencies
        run: |
          pip install mkdocs-material
          pip install "mkdocstrings[python]"
          pip install mike
          pip install pymarkdownlnt
          pip install yq
          pip install -e .

      - name: Lint documentation
        run: |
          pymarkdownlnt scan -r -e ./.venv -e ./.git -e ./.github -e ./data -e ./djangoapi_guard -e ./tests .

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

      - name: Get and Update Version
        id: get_version
        run: |
          CURRENT_VERSION=$(yq -r '.aliases.latest' .mike.yml)

          if [[ ! $CURRENT_VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "::error::Invalid version format in .mike.yml: $CURRENT_VERSION"
            exit 1
          fi
          echo "CURRENT_VERSION=$CURRENT_VERSION" >> $GITHUB_ENV

          if [[ -n "${{ secrets.DOCS_VERSION }}" ]]; then
            STORED_VERSION=${{ secrets.DOCS_VERSION }}
            echo "STORED_VERSION=$STORED_VERSION" >> $GITHUB_ENV
          else
            echo "::error::DOCS_VERSION secret not found"
            exit 1
          fi

          if [[ "$CURRENT_VERSION" != "$STORED_VERSION" ]]; then
            echo "::notice::Updating DOCS_VERSION from $STORED_VERSION to $CURRENT_VERSION"
            echo "VERSION=$CURRENT_VERSION" >> $GITHUB_ENV
            echo "UPDATE_SECRET=true" >> $GITHUB_ENV
          else
            echo "::notice::Versions match ($CURRENT_VERSION), no update needed"
            echo "VERSION=$STORED_VERSION" >> $GITHUB_ENV
            echo "UPDATE_SECRET=false" >> $GITHUB_ENV
          fi

      - name: Update Docs Version Secret
        if: ${{ env.UPDATE_SECRET == 'true' }}
        uses: rennf93/github-actions-secrets-mgmt@v1.5
        with:
          OWNER: ${{ github.repository_owner }}
          REPOSITORY: ${{ github.event.repository.name }}
          ACCESS_TOKEN: ${{ secrets.PAT_TOKEN }}
          SECRET_NAME: DOCS_VERSION
          SECRET_VALUE: ${{ env.VERSION }}

      - name: Deploy documentation
        run: |
          mike deploy --push ${{ env.VERSION }}
          mike alias --update-aliases --push ${{ env.VERSION }} latest
          mike set-default --push latest

      - name: Deploy to GitHub Pages
        run: |
          mike list
          git push origin gh-pages --force

      - name: Update Context7 Documentation
        id: context7
        uses: rennf93/upsert-context7@1.1
        with:
          operation: refresh

      - name: Show result
        run: |
          echo "Success: ${{ steps.context7.outputs.success }}"
          echo "Status: ${{ steps.context7.outputs.status-code }}"
          echo "Message: ${{ steps.context7.outputs.message }}"