docs: Integrate Doxygen documentation in Sphinx documentation

There is no perfect integration, unfortunately. But this should get
the API documentation hosted and readable in its best form.

The doxygen-awesome-css theme is used to bring the theme more
in line with the rest of the Cloe documentation.

Author: cassava

.github/workflows/build-api-docs.yaml

@@ -1,25 +1,28 @@
-name: Build User Documentation
+name: Build Documentation
 
 on:
   pull_request:
     paths:
       - "docs/**"
+      - "*.hpp"
 
 jobs:
   sphinx:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-      - run: mkdir build
-      - run: sudo apt-get update && sudo apt-get install -y git
-      - name: Build documentation
+      - name: Build Doxygen documentation
+        uses: mattnotmitt/[email protected]
+        with:
+          working-directory: docs
+      - name: Build Sphinx documentation
         uses: ammaraskar/sphinx-action@master
         with:
-          docs-folder: docs/
+          docs-folder: docs
           build-command: make html
       - name: Upload documentation
         uses: actions/upload-artifact@v3
         with:
-          name: user-documentation
-          path: build/sphinx/html/
+          name: documentation
+          path: docs/_build/html/

.github/workflows/build-user-docs.yaml renamed to .github/workflows/build-docs.yaml

@@ -7,6 +7,10 @@ setup.sh
 # Standard out-of-source build
 build/
 
+# Documentation
+docs/_build/
+docs/_extra/
+
 # Files generated by Conan:
 conan_options.txt
 conan.lock
@@ -33,7 +37,7 @@ compile_commands.json
 # Python object/temporary files
 __pycache__
 *.pyc
-.mypy_cache
+.mypy_cache/
 
 # C/C++ object/temporary files
 *.a

.gitignore

@@ -42,8 +42,7 @@ help::
 	$(call print_help_target, status, "show status of each of the Conan packages")
 	$(call print_help_target, smoketest-deps, "build system test pre-requisites")
 	$(call print_help_target, smoketest, "run system tests")
-	$(call print_help_target, sphinx, "generate Sphinx documentation")
-	$(call print_help_target, doxygen, "generate Doxygen documentation")
+	$(call print_help_target, docs, "generate documentation")
 	$(call print_help_target, deploy, "deploy Cloe to INSTALL_DIR [=${INSTALL_DIR}]")
 	$(call print_help_target, deploy-cli, "install ${_yel}cloe-launch${_rst} with ${_dim}${PIPX}${_rst}")
 	$(call print_help_target, export-cli, "export ${_yel}cloe-launch-profile${_rst} Conan recipe")
@@ -78,18 +77,13 @@ deploy-cli:
 export-cli:
 	${MAKE} -C cli conan-profile
 
-.PHONY: sphinx
-sphinx:
+.PHONY: docs
+docs:
+	$(call print_header, "Generating Doxygen documentation...")
+	${MAKE} -C docs doxygen
 	$(call print_header, "Generating Sphinx documentation...")
-	mkdir -p ${BUILD_DIR}/sphinx
 	${MAKE} -C docs html
 
-.PHONY: doxygen
-doxygen:
-	$(call print_header, "Generating Doxygen documentation...")
-	mkdir -p ${BUILD_DIR}/doxygen
-	doxygen Doxyfile
-
 .PHONY: smoketest-deps
 smoketest-deps: export-cli smoketest-deps-select
 

Makefile

@@ -40,6 +40,12 @@ The following third-party libraries are included in the Cloe repository:
   - Website: http://getbootstrap.com
   - Source: engine/webui/bootstrap.min.css
 
+- Doxygen-Awesome-CSS
+  - License: MIT
+  - License-Source: docs/_vendor/doxygen-awesome/LICENSE
+  - Website: https://jothepro.github.io/doxygen-awesome-css
+  - Source: docs/_vendor/doxygen-awesome
+
 The following third-party libraries are used by this project (these are usually
 installed with the help of Conan):