test-docs-build.yml

name: Test Documentation Build

on:
    pull_request:
        branches:
            - main
            - develop
        paths:
            - "docs/**"
            - "mkdocs.yml"
            - "workflow/scripts/**"
            - ".github/workflows/test-docs-build.yml"
    push:
        branches:
            - prepare_release
        paths:
            - "docs/**"
            - "mkdocs.yml"
            - "workflow/scripts/**"
    workflow_dispatch:

jobs:
    test-build:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Set up Python
              uses: actions/setup-python@v5
              with:
                  python-version: "3.12"

            - name: Install dependencies
              run: |
                  python -m pip install --upgrade pip
                  pip install mkdocs
                  pip install mkdocs_gen_files
                  pip install "mkdocstrings[python]"
                  pip install mkdocs-awesome-nav
                  pip install mkdocs-material
                  pip install mkdocs-include-dir-to-nav
                  pip install python-markdown-math
                  pip install mike>=2.0.0

            - name: Test documentation build
              run: |
                  mkdocs build
                  echo "✓ Documentation builds successfully"

            - name: Upload build artifacts
              if: failure()
              uses: actions/upload-artifact@v4
              with:
                  name: docs-build-output
                  path: site/
                  retention-days: 5

            - name: Validate navigation
              run: |
                  python -c "
                  import yaml
                  with open('mkdocs.yml', 'r') as f:
                      config = yaml.safe_load(f)
                  print('✓ Navigation structure is valid')
                  "

            - name: Upload build artifacts
              if: failure()
              uses: actions/upload-artifact@v4
              with:
                  name: failed-build
                  path: site/