CI-docs.yml

---
name: CI-docs
# Build and deploy docs to gh-pages

on:
  workflow_dispatch:
  pull_request:
    branches: [main]
    types: [opened, closed, synchronize]

jobs:

  docs:
    runs-on: ubuntu-latest

    steps:
      - name: checkout
        uses: actions/checkout@v4

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

      - name: Python dependencies
        run: |
          pip install '.[doc]'

      - name: Check for non-ASCII characters
        run: |
          output=$(perl -ne 'print if /[^[:ascii:]]/' docs/source/*)
          if [ -n "$output" ]; then
            echo "Non-ASCII characters found in documentation."
            exit 1
          fi

      - name: Check that all applications are documented
        run: |-
          scripts=$(grep 'scripts.simtools-' pyproject.toml | sed -e 's/^scripts\.//' -e 's/ =.*$//')
          FULLY_DOCUMENTED="TRUE"
          for S in $scripts; do
              if [ ! -e "docs/source/user-guide/applications/$S.rst" ]; then
                echo "Undocumented script: $S"
                FULLY_DOCUMENTED="FALSE"
              fi
          done
          if [[ "$FULLY_DOCUMENTED" = "FALSE" ]]; then
              exit 1
          fi
        shell: /usr/bin/bash -e {0}

      - name: Check for complete API documentation
        run: |-
          MODULES=$(find src/simtools -type f -name "*.py" \
            ! -path "src/simtools/applications/*" \
            ! -name "__init__.py" ! -name "version.py" \
            ! -path "src/simtools/_*" -prune)
          FULLY_DOCUMENTED="TRUE"
          for M in "${MODULES[@]}"; do
              module=$(basename "$M" .py)
              if ! grep -q "$module" docs/source/api-reference/*.md; then
                echo "Undocumented module: $module"
                FULLY_DOCUMENTED="FALSE"
              fi
          done
          if [[ "$FULLY_DOCUMENTED" = "FALSE" ]]; then
              exit 1
          fi

      - name: Build docs
        shell: bash -l {0}
        run: |
          make -C docs/ html
          exit_code=$?
          if [ $exit_code -ne 0 ]; then
            echo "Make command failed with exit code $exit_code"
            exit $exit_code
          fi
          touch docs/build/html/.nojekyll

      - name: Deploy to github pages
        # only run when PR is merged
        if: github.event.pull_request.merged
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: docs/build/html
          CLEAN: true