docs.yml

# SPDX-License-Identifier: PMPL-1.0-or-later
# Documentation workflow for cicd-hyper-a
# Builds AsciiDoc documentation and deploys to GitHub Pages

name: Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - '*.adoc'
      - '.github/workflows/docs.yml'
  pull_request:
    branches: [main]
    paths:
      - 'docs/**'
      - '*.adoc'
  workflow_dispatch:

permissions: read-all

concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: true

env:
  ASCIIDOCTOR_VERSION: '2.0.23'

jobs:
  # ============================================================================
  # Build Documentation
  # ============================================================================
  build-docs:
    name: Build AsciiDoc
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Ruby
        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
        with:
          ruby-version: '3.2'
          bundler-cache: true

      - name: Install AsciiDoctor
        run: |
          gem install asciidoctor --version ${{ env.ASCIIDOCTOR_VERSION }}
          gem install asciidoctor-diagram
          gem install asciidoctor-rouge
          gem install asciidoctor-pdf
          gem install rouge

      - name: Create output directories
        run: |
          mkdir -p _site/docs
          mkdir -p _site/api

      - name: Build main documentation
        run: |
          # Build README as index
          asciidoctor \
            --backend html5 \
            --destination-dir _site \
            --out-file index.html \
            --attribute toc=left \
            --attribute toclevels=3 \
            --attribute source-highlighter=rouge \
            --attribute icons=font \
            --attribute sectanchors \
            --attribute sectlinks \
            --attribute linkcss \
            --attribute stylesheet=asciidoctor.css \
            README.adoc

          # Build all adoc files in docs/
          for file in docs/*.adoc; do
            if [ -f "$file" ]; then
              basename=$(basename "$file" .adoc)
              asciidoctor \
                --backend html5 \
                --destination-dir _site/docs \
                --out-file "${basename}.html" \
                --attribute toc=left \
                --attribute toclevels=3 \
                --attribute source-highlighter=rouge \
                --attribute icons=font \
                --attribute sectanchors \
                --attribute sectlinks \
                "$file"
            fi
          done

          # Build other root-level adoc files
          for file in CONTRIBUTING.adoc MAINTAINERS.adoc PALIMPSEST.adoc CII-ENFORCEMENT.adoc ROADMAP-v1.0.0.adoc; do
            if [ -f "$file" ]; then
              basename=$(basename "$file" .adoc)
              asciidoctor \
                --backend html5 \
                --destination-dir _site \
                --out-file "${basename}.html" \
                --attribute toc=left \
                --attribute toclevels=3 \
                --attribute source-highlighter=rouge \
                --attribute icons=font \
                --attribute sectanchors \
                "$file"
            fi
          done

      - name: Build PDF documentation
        run: |
          mkdir -p _site/pdf

          asciidoctor-pdf \
            --destination-dir _site/pdf \
            --out-file cicd-hyper-a-manual.pdf \
            --attribute pdf-theme=default \
            --attribute pdf-fontsdir=GEM_FONTS_DIR \
            --attribute toc \
            --attribute toclevels=3 \
            README.adoc || echo "PDF generation skipped or failed"

      - name: Generate Rust API documentation
        run: |
          # Install Rust using official action (more secure than curl | sh)
          # Note: In a real workflow, we would use rust-toolchain file or setup action
          # For documentation purposes, we'll use a safer approach
          if ! command -v cargo &> /dev/null; then
            echo "Rust not found, installing..."
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs > rustup-install.sh
            chmod +x rustup-install.sh
            ./rustup-install.sh -y --profile minimal --default-toolchain stable
            source $HOME/.cargo/env
            rm rustup-install.sh
          fi

          # Generate rustdoc
          cargo doc --workspace --no-deps --document-private-items

          # Copy to site
          cp -r target/doc/* _site/api/

      - name: Generate Haskell API documentation
        working-directory: registry
        run: |
          # Install GHC and Cabal
          sudo apt-get update
          sudo apt-get install -y ghc cabal-install

          cabal update
          cabal haddock --haddock-html --haddock-hyperlink-source || true

          # Copy Haddock output if it exists
          if [ -d "dist-newstyle/build/*/ghc-*/cicd-hyper-a-*/doc/html/cicd-hyper-a" ]; then
            mkdir -p ../_site/api/haskell
            cp -r dist-newstyle/build/*/ghc-*/cicd-hyper-a-*/doc/html/cicd-hyper-a/* ../_site/api/haskell/
          fi

      - name: Create navigation index
        run: |
          cat << 'EOF' > _site/docs/index.html
          <!DOCTYPE html>
          <html lang="en">
          <head>
            <meta charset="UTF-8">
            <meta name="viewport" content="width=device-width, initial-scale=1.0">
            <title>cicd-hyper-a Documentation</title>
            <style>
              body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; }
              h1 { color: #333; }
              ul { list-style-type: none; padding: 0; }
              li { margin: 0.5rem 0; }
              a { color: #0066cc; text-decoration: none; }
              a:hover { text-decoration: underline; }
              .section { margin: 2rem 0; }
            </style>
          </head>
          <body>
            <h1>cicd-hyper-a Documentation</h1>

            <div class="section">
              <h2>User Documentation</h2>
              <ul>
                <li><a href="../index.html">README - Project Overview</a></li>
                <li><a href="user-guide.html">User Guide</a></li>
                <li><a href="CICD-GUIDEBOOK.html">CI/CD Guidebook</a></li>
                <li><a href="SESSION-LOG.html">Session Log</a></li>
              </ul>
            </div>

            <div class="section">
              <h2>Technical Specifications</h2>
              <ul>
                <li><a href="ADA-TUI-AUDIT-SPEC.html">ADA TUI Audit Specification</a></li>
                <li><a href="../ROADMAP-v1.0.0.html">Roadmap v1.0.0</a></li>
                <li><a href="../CII-ENFORCEMENT.html">CII Enforcement</a></li>
              </ul>
            </div>

            <div class="section">
              <h2>Contributing</h2>
              <ul>
                <li><a href="../CONTRIBUTING.html">Contributing Guide</a></li>
                <li><a href="../MAINTAINERS.html">Maintainers</a></li>
              </ul>
            </div>

            <div class="section">
              <h2>API Reference</h2>
              <ul>
                <li><a href="../api/cicd_hyper_a_cli/index.html">Rust CLI API</a></li>
                <li><a href="../api/cicd_hyper_a_adapters/index.html">Rust Adapters API</a></li>
                <li><a href="../api/haskell/index.html">Haskell Registry API</a></li>
              </ul>
            </div>

            <div class="section">
              <h2>Downloads</h2>
              <ul>
                <li><a href="../pdf/cicd-hyper-a-manual.pdf">PDF Manual</a></li>
              </ul>
            </div>
          </body>
          </html>
          EOF

      - name: Upload documentation artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: documentation
          path: _site
          retention-days: 7

      - name: Upload Pages artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: _site

  # ============================================================================
  # Validate Documentation
  # ============================================================================
  validate-docs:
    name: Validate Documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Ruby
        uses: ruby/setup-ruby@c4e5b1316158f92e3d49443a9d58b31d25ac0f8f # v1.306.0
        with:
          ruby-version: '3.2'

      - name: Install AsciiDoctor
        run: gem install asciidoctor

      - name: Validate AsciiDoc syntax
        run: |
          errors=0
          for file in $(find . -name "*.adoc" -not -path "./.git/*"); do
            echo "Validating $file..."
            if ! asciidoctor --backend html5 --out-file /dev/null "$file" 2>&1; then
              echo "::error file=$file::AsciiDoc validation failed"
              errors=$((errors + 1))
            fi
          done

          if [ $errors -gt 0 ]; then
            echo "::error::$errors file(s) failed validation"
            exit 1
          fi

          echo "All AsciiDoc files validated successfully"

      - name: Check for broken internal links
        run: |
          # Extract and validate internal links from adoc files
          for file in $(find . -name "*.adoc" -not -path "./.git/*"); do
            # Extract link references
            grep -oE 'link:[^[]+\[' "$file" 2>/dev/null | sed 's/link://;s/\[$//' | while read -r link; do
              # Skip external links
              if [[ "$link" == http* ]]; then
                continue
              fi

              # Check if referenced file exists
              dir=$(dirname "$file")
              if [ ! -f "$dir/$link" ] && [ ! -f "$link" ]; then
                echo "::warning file=$file::Potentially broken link: $link"
              fi
            done
          done

  # ============================================================================
  # Deploy to GitHub Pages
  # ============================================================================
  deploy-pages:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    needs: [build-docs, validate-docs]
    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

  # ============================================================================
  # Documentation Status
  # ============================================================================
  docs-status:
    name: Documentation Status
    runs-on: ubuntu-latest
    needs: [build-docs, validate-docs]
    if: always()
    steps:
      - name: Check documentation status
        run: |
          echo "## Documentation Build Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [[ "${{ needs.build-docs.result }}" == "success" ]]; then
            echo "- :white_check_mark: Documentation built successfully" >> $GITHUB_STEP_SUMMARY
          else
            echo "- :x: Documentation build failed" >> $GITHUB_STEP_SUMMARY
          fi

          if [[ "${{ needs.validate-docs.result }}" == "success" ]]; then
            echo "- :white_check_mark: Documentation validation passed" >> $GITHUB_STEP_SUMMARY
          else
            echo "- :warning: Documentation validation had issues" >> $GITHUB_STEP_SUMMARY
          fi