docs-validation.yml

name: Documentation Validation

on:
  push:
    branches:
      - main
    paths:
      - 'src/main/asciidoc/**/*.adoc'
      - 'pom.xml'
      - '.github/workflows/docs-validation.yml'
  pull_request:
    paths:
      - 'src/main/asciidoc/**/*.adoc'
      - 'pom.xml'
      - '.github/workflows/docs-validation.yml'

permissions:
  contents: write

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    name: Validate Documentation

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip

      - name: Setup Graphviz
        uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2

      - name: Install D2
        run: |
          curl -fsSL https://d2lang.com/install.sh | sh -s --
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          # Verify D2 installation
          export PATH="$HOME/.local/bin:$PATH"
          d2 --version

      - name: Set up Java
        uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c # v6.0.0
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Run documentation validator
        run: |
          python docs-validator.py

      - name: Test documentation build (verify diagrams work)
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          mvn generate-resources

      - name: Validate HTML output
        run: |
          if [ -d "target/generated-docs" ]; then
            python -m pip install --break-system-packages html5validator
            html5validator --root target/generated-docs --skip-non-html --show-warnings \
              --ignore 'amzn-kf8' 'not allowed as child of element "div"' 'violates nesting rules'
          else
            echo "No generated docs found"
            exit 1
          fi