doc.yml

name: doc
on:
  workflow_dispatch:
  workflow_call:

concurrency:
  group: doc-${{github.ref}}-${{github.event.pull_request.number || github.run_number}}-${{github.workflow}}
  cancel-in-progress: true

env:
  CMAKE_PRESET: doc
  CELER_UPLOAD_DOC:  >-
    ${{  github.ref_name == 'develop'
      || contains(github.ref_name, 'backports/')
      || contains(github.head_ref, 'release-')
      || contains(github.event.pull_request.labels.*.name, 'documentation')
    }}

jobs:
  dev:
    env:
      CELER_TARGET: doxygen
      CELER_UPLOAD_DIR: build/doc/doxygen-html
    runs-on: ubuntu-24.04
    steps:
      - name: Install dependencies
        run: |
            sudo apt-get -y update
            sudo apt-get -y install \
                cmake graphviz ninja-build doxygen nlohmann-json3-dev
      - name: Check out Celeritas
        uses: actions/checkout@v4
        with:
          fetch-depth: 383
          fetch-tags: true
      - name: Configure celeritas
        # Turn warnings into errors only for PRs
        # Disable expensive graphs for PRs also
        run: |
          ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
          mkdir build && cd build
          cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE \
            ${{ github.workflow == 'pull_request'
             && '-DDOXYGEN_WARN_AS_ERROR="YES" -DDOXYGEN_HAVE_DOT="NO"'
             || ''}} \
            ..
      - name: Build documentation
        run: |
          cmake --build --preset=${CMAKE_PRESET} --target ${CELER_TARGET}
          find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
      - name: Upload artifacts
        if: ${{env.CELER_UPLOAD_DOC}}
        uses: actions/upload-artifact@v4
        with:
          path: ${{env.CELER_UPLOAD_DIR}}
          name: doc-dev
          if-no-files-found: error
          overwrite: true
          retention-days: 1 # developer docs can be large

  user:
    runs-on: ubuntu-24.04
    env:
      CELER_TARGET: doc
      CELER_UPLOAD_DIR: build/doc/html
    steps:
      - name: Install dependencies
        run: |
            sudo apt-get -y update
            sudo apt-get -y install \
                cmake graphviz ninja-build doxygen nlohmann-json3-dev
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10' 
      - name: Check out Celeritas
        uses: actions/checkout@v4
        with:
          fetch-depth: 383
          fetch-tags: true
      - name: Install Python packages
        run: |
            pip install --upgrade pip
            pip install -r scripts/doc-requirements.txt
      - name: Configure celeritas
        run: |
          ln -fs scripts/cmake-presets/ci-ubuntu-github.json CMakeUserPresets.json
          mkdir build && cd build
          cmake --preset=${CMAKE_PRESET} --log-level=VERBOSE \
            ${{ github.workflow == 'pull_request'
             && '-DDOXYGEN_WARN_AS_ERROR="YES" -DCELERITAS_SPHINX_USER_HTML_ARGS="-W;--keep-going"'
             || ''}} \
            ..
      - name: Build documentation
        run: |
          cmake --build --preset=${CMAKE_PRESET} --target ${CELER_TARGET}
          find ${CELER_UPLOAD_DIR} -name '*.md5' -exec rm {} +
      - name: Upload artifacts
        if: ${{env.CELER_UPLOAD_DOC}}
        uses: actions/upload-artifact@v4
        with:
          path: ${{env.CELER_UPLOAD_DIR}}
          name: doc-user
          if-no-files-found: error
          overwrite: true
          retention-days: 7 # user docs might need review

# vim: set nowrap tw=100: