docs.yml

name: Generate Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'module/**'
      - 'devtools/**'
      - 'requirements/**'
      - 'pyproject.toml'
      - '.github/workflows/docs.yml'
      # Note: 'docs/**' is intentionally excluded to prevent infinite loop
  workflow_dispatch:  # Allow manual triggering

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # Required to commit and push changes
      pull-requests: read  # Optional: for PR context
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0  # Full history for proper git operations
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'
          cache: 'pip'
      
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y libcairo2-dev pkg-config
      
      - name: Create docs venv
        run: |
          python -m pip install --upgrade pip
          make venv-docs
      
      - name: Generate module documentation
        env:
          PYTHONPATH: ${{ github.workspace }}
          KIVY_NO_ARGS: "1"
          DOCS_SKIP_KIVY: "1"
        working-directory: ${{ github.workspace }}
        run: |
          venv-docs/bin/python -m devtools.docs_export --out docs/site/content/auto --hugo
      
      - name: Generate Mermaid diagram and enum overview
        env:
          PYTHONPATH: ${{ github.workspace }}
        working-directory: ${{ github.workspace }}
        run: |
          venv-docs/bin/python -m devtools.diagram_export --out docs/site/content/models.mmd --enums-out docs/site/content/enums.md
      
      - name: Check for changes
        id: verify-changed-files
        run: |
          if [ -n "$(git status --porcelain docs/)" ]; then
            echo "changed=true" >> $GITHUB_OUTPUT
          else
            echo "changed=false" >> $GITHUB_OUTPUT
          fi
      
      - name: Commit and push changes
        if: steps.verify-changed-files.outputs.changed == 'true'
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          # Add all changes in docs directory (only files that exist and were modified)
          git add docs/
          git commit -m "docs: auto-generate documentation [skip ci]" || exit 0
          # Pull latest changes and rebase our commit on top
          git pull --rebase origin main
          git push origin HEAD:main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}