docs.yml

name: Documentation

on:
  push:
    tags:
      - "v*.*.*"
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-docs:
    name: Build
    runs-on: ubuntu-20.04
    steps:
      - name: Fetch the package's repository
        uses: actions/checkout@v4

      - name: Install dependencies (doxygen+sphinx+breathe+exhale toolchain)
        run: |
          sudo apt-get update
          sudo apt-get install -q -y --no-install-recommends python3-pip doxygen
          sudo apt-get install -q -y --no-install-recommends latexmk texlive-latex-extra tex-gyre texlive-fonts-recommended texlive-latex-recommended
          python3 -m pip install --upgrade pip
          pip3 install exhale sphinx-sitemap sphinx-design sphinx-notfound-page
          pip3 install sphinxawesome-theme --pre
          pip3 install "sphinx<7,>6"

      - name: Parse C++ API with Doxygen
        working-directory: ${{github.workspace}}/docs
        shell: bash
        run: doxygen Doxyfile_cpp

      - name: Parse ROS1 Interface with Doxygen
        working-directory: ${{github.workspace}}/docs
        shell: bash
        run: doxygen Doxyfile_ros1

      - name: Build Python API (parsed by Sphinx)
        run: python -m pip install -v ./library/python/

      - name: Build documentation site
        working-directory: ${{github.workspace}}/docs
        shell: bash
        run: sphinx-build -b html . _build/html

      - name: Bundle site sources into tarball
        shell: bash
        run: |
          tar \
            --dereference --hard-dereference \
            --directory ${{github.workspace}}/docs/_build/html/ \
            -cvf ${{github.workspace}}/docs/artifact.tar \
            --exclude=.git \
            --exclude=.github \
            .

      - name: Upload tarball as GH Pages artifact
        uses: actions/upload-artifact@v4
        with:
          name: github-pages
          path: ${{github.workspace}}/docs/artifact.tar
          retention-days: 3

      - name: Build documentation PDF
        working-directory: ${{github.workspace}}/docs
        shell: bash
        run: sphinx-build -M latexpdf . _build/latex

      - name: Upload PDF
        uses: actions/upload-artifact@v4
        with:
          name: documentation-pdf
          path: ${{github.workspace}}/docs/_build/latex/latex/wavemap.pdf
          retention-days: 3

  draft-release:
    name: Draft Release
    if: startsWith(github.event.ref, 'refs/tags/v')
    needs: build-docs
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - uses: actions/download-artifact@v4.1.8
        with:
          name: documentation-pdf

      - name: Create Release
        id: create_release
        uses: softprops/action-gh-release@v2.0.8
        with:
          files: "wavemap.pdf"

  publish-docs:
    name: Publish to GH Pages
    if: github.ref == 'refs/heads/main'
    needs: build-docs
    runs-on: ubuntu-20.04
    permissions:
      contents: read
      pages: write
      id-token: write
    concurrency:
      group: "pages"
      cancel-in-progress: true
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Deploy uploaded docs to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4