docs.yml

name: Generate Documentation

on:
  push:
    branches: 'trunk'
  workflow_dispatch:

env:
  LDMX_DOCKER_TAG: ldmx/dev:latest

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout ldmx-sw
      uses: actions/checkout@v4
      with:
        submodules: 'recursive'

    - name: Compile and Install ldmx-sw
      uses: ./.github/actions/setup

    # The rest of the steps are building docs
    #   Since the build is made and tested above,
    #   the docs are only updated if the build passes
    # They need to be in the same job as the build becuase
    #   the sphinx-apidoc command needs the python package
    #   structured like a normal python package. 

    # Runs doxygen doxygen.conf in the docs/ directory
    - name: Run Doxygen to build C++ Docs
      uses: mattnotmitt/doxygen-action@v1.9
      with:
        doxyfile-path: docs/doxygen.conf/doxyfile #relative to working directory

    # sphinx is a python package, so we need to setup python on this runner
    - name: Setup Python for Sphinx
      uses: actions/setup-python@v4
      with:
        python-version: 3.11
    
    # Runs sphinx-apidoc and sphinx-build in the docs/ directory
    #   sphinx-apidoc requires the python files to be packaged together
    #   like a python module would be. The simplest way to achieve
    #   this form is to build and install ldmx-sw.
    #   we also need to create the __init__.py files which aren't required by
    #   Python3 packages but is necessary for sphinx-apidoc to recognize a
    #   directory as a module to document
    - name: Run Sphinx to build python Docs
      run: |
          python3 -m pip install -U pip
          python3 -m pip install Sphinx Pillow
          find install/python/LDMX -type d -exec touch {}/__init__.py ';'
          sphinx-apidoc --force --no-toc -o docs/sphinx.conf/ install/python/LDMX
          sudo `which sphinx-build` docs/sphinx.conf docs/html/python
      shell: bash

    # Copy the generated documentation to github as a pages artifact
    #   This copies all the html files in the docs/html directory
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v2
      with:
        path: ./docs/html

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2