python-docs.yml

# Comprehensive Documentation Generation Pipeline
# Generates HTML and Markdown documentation with enhanced features
name: Documentation Generation & Deployment
permissions:
  contents: read
  actions: write

on:
  push:
    branches: [ main, develop, bugfix-* ]
    paths:
      - '**.py'
      - 'doc/**'
      - 'scripts/generate-docs.py'
  pull_request:
    paths:
      - '**.py'
      - 'doc/**'
      - 'scripts/generate-docs.py'

env:
  PYTHON_VERSION: '3.11'
  DOCS_SOURCE: 'doc/codeDocs'
  DOCS_OUTPUT: 'documentation-artifacts'

jobs:
  build-documentation:
    name: Build Multi-Format Documentation
    runs-on: ubuntu-latest
    outputs:
      docs-version: ${{ steps.version.outputs.version }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python Environment
        uses: ./.github/actions/setup-python-env
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          install-dev-reqs: 'false'
          install-docs-reqs: 'true'

      - name: Install system dependencies
        run: |
          sudo apt-get update -qq
          sudo apt-get install -y --no-install-recommends \
            graphviz \
            pandoc

      - name: Set documentation version
        id: version
        run: |
          VERSION="$(date +'%Y.%m.%d')-$(git rev-parse --short HEAD)"
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          echo "Documentation version: $VERSION"

      - name: Clean previous builds
        run: |
          echo "🧹 Cleaning previous documentation builds..."
          rm -rf doc/codeDocs/_build/ || true
          rm -rf documentation-output/ || true
          mkdir -p ${{ env.DOCS_OUTPUT }}

      - name: Build comprehensive documentation
        run: |
          echo "🚀 Building enhanced documentation with improved error handling..."
          cd ${{ github.workspace }}

          # Set Python path for imports
          export PYTHONPATH=.

          # Build using our improved build script (which now handles failures gracefully)
          if ./scripts/build-docs.sh; then
            echo "✅ Documentation build completed successfully"
          else
            echo "⚠️  Documentation build had some issues but may have produced partial results"
            # Don't fail the CI if we got partial documentation
            exit 0
          fi

      - name: Update manifest with CI information
        run: |
          if [ -f documentation-output/manifest.json ]; then
            echo "📝 Adding CI metadata to manifest..."
            python3 -c "import json; m=json.load(open('documentation-output/manifest.json')); m.update({'ci_run_number':'${{ github.run_number }}','ci_sha':'${{ github.sha }}','ci_ref':'${{ github.ref }}','repository':'${{ github.repository }}','ci_build_url':'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'}); json.dump(m,open('documentation-output/manifest.json','w'),indent=2)"
            echo "✅ Updated manifest with CI information"
          fi

      - name: Package documentation artifacts
        run: |
          echo "📦 Verifying documentation artifacts from build script..."
          
          # Our build script already creates documentation-output/ directory
          if [ -d "documentation-output" ]; then
            echo "✅ Documentation artifacts found"
            ls -la documentation-output/
            
            # Copy to CI-expected location if needed
            if [ ! -d "${{ env.DOCS_OUTPUT }}" ]; then
              cp -r documentation-output "${{ env.DOCS_OUTPUT }}"
            fi
          else
            echo "⚠️  No documentation artifacts found - creating minimal structure"
            mkdir -p "${{ env.DOCS_OUTPUT }}"
            
            # Create a basic manifest for failed build
            cat > "${{ env.DOCS_OUTPUT }}/manifest.json" << EOF
          {
            "version": "${{ steps.version.outputs.version }}",
            "generated_at": "$(date -u -Iseconds)",
            "repository": "${{ github.repository }}",
            "branch": "${{ github.ref_name }}",
            "commit": "${{ github.sha }}",
            "status": "build_failed",
            "message": "Documentation build failed but CI completed"
          }
          EOF
          fi
          
          echo "📊 Final documentation summary:"
          ls -la "${{ env.DOCS_OUTPUT }}/" || true

      - name: Cleanup temporary files
        run: |
          echo "🧹 Cleaning up temporary files..."
          cd ${{ env.DOCS_SOURCE }}
          # Remove build artifacts but keep source
          rm -rf _build/doctrees/ || true
          rm -rf _build/latex/*.aux _build/latex/*.log _build/latex/*.out _build/latex/*.toc || true
          find _static/diagrams/ -name '*.dot' -delete || true
          # Clean Python cache
          find . -type d -name '__pycache__' -exec rm -rf {} + || true
          find . -name '*.pyc' -delete || true
          echo "Cleanup completed"

      - name: Upload HTML Documentation
        uses: actions/upload-artifact@v4
        if: hashFiles('documentation-artifacts/html/**') != ''
        with:
          name: html-documentation
          path: ${{ env.DOCS_OUTPUT }}/html/
          retention-days: 90

      - name: Upload Markdown Documentation
        uses: actions/upload-artifact@v4
        if: hashFiles('documentation-artifacts/markdown/**') != ''
        with:
          name: markdown-documentation
          path: ${{ env.DOCS_OUTPUT }}/markdown/
          retention-days: 90

      - name: Upload PDF Documentation
        uses: actions/upload-artifact@v4
        if: hashFiles('documentation-artifacts/*.pdf') != ''
        with:
          name: pdf-documentation
          path: ${{ env.DOCS_OUTPUT }}/*.pdf
          retention-days: 90

      - name: Upload Complete Documentation Archive
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: complete-documentation-${{ steps.version.outputs.version }}
          path: ${{ env.DOCS_OUTPUT }}/
          retention-days: 90