Add CI workflow for documentation generation

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Documentation
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-docs:
+    name: Build docs
+    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: |
+          apt-get update
+          apt-get install -q -y --no-install-recommends python3-pip doxygen
+          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: ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs
+        shell: bash
+        run: doxygen Doxyfile_cpp
+
+      - name: Parse ROS1 Interface with Doxygen
+        working-directory: ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/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: ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs
+        shell: bash
+        run: sphinx-build -b html . _build/html
+
+      - name: Bundle site sources into tarball
+        shell: bash
+        run: |
+          tar \
+            --dereference --hard-dereference \
+            --directory ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs/_build/html/ \
+            -cvf ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs/artifact.tar \
+            --exclude=.git \
+            --exclude=.github \
+            .
+
+      - name: Upload tarball as GH Pages artifact
+        uses: actions/upload-artifact@main
+        with:
+          name: github-pages
+          path: ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs/artifact.tar
+          retention-days: 1
+
+      - name: Build documentation PDF
+        working-directory: ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs
+        shell: bash
+        run: sphinx-build -M latexpdf . _build/latex
+
+      - name: Upload PDF
+        uses: actions/upload-artifact@main
+        with:
+          name: documentation-pdf
+          path: ${{ env.CATKIN_WS_PATH }}/src/${{ env.REPOSITORY_NAME }}/docs/_build/latex/latex/wavemap.pdf
+          retention-days: 3

.github/workflows/python.yml

@@ -23,6 +23,7 @@ jobs:
 
   test:
     name: Test
+    needs: build
     runs-on: ubuntu-20.04
     steps:
       - name: Fetch the package's repository

docs/pages/installation/cmake.rst

@@ -1,5 +1,5 @@
-C++ Library (CMake)
-###################
+C++ (CMake)
+###########
 .. highlight:: bash
 .. rstcheck: ignore-directives=tab-set-code
 .. rstcheck: ignore-roles=gh_file