Setup Exhale to include Doxygen in Sphinx

Author: schmoelder

.gitignore

@@ -71,6 +71,8 @@ doc/tex/*.gitinfo
 doc/tex/*.synctex.gz
 doc/tex/*.pdf
 doc/tex/docs/*.aux
+doc/doxyoutput/
+doc/api/
 
 ### Ignore IDE files ###
 .vs/

doc/README.md

@@ -34,6 +34,11 @@ Ensure you have [mamba](https://mamba.readthedocs.io/en/latest/installation.html
 To build the documentation for all releases and the master branch, run:
 
 ```sh
-sphinx-multiversion ./ ./build/
+sphinx-multiversion ./ ./build/ -D 'exhale_args.containmentFolder=${sourcedir}/api'
 ```
 
+On Windows, use the following command:
+
+```powershell
+sphinx-multiversion ./ ./build/ -D exhale_args.containmentFolder=${sourcedir}/api
+```

doc/conf.py

@@ -32,6 +32,8 @@
     'sphinxcontrib.bibtex',
     'sphinx_multiversion',
     "myst_parser",
+    'breathe',
+    'exhale',
 ]
 
 # Bibliography
@@ -50,6 +52,28 @@
 smv_remote_whitelist = r"^origin$"          # Use branches from remote origin
 smv_outputdir_format = '{ref.name}'         # Use the branch/tag name
 
+# Setup the breathe extension
+breathe_projects = {
+    "CADET": "./doxyoutput/xml"
+}
+breathe_default_project = "CADET"
+
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./api",
+    "rootFileName":          "library_root.rst",
+    "doxygenStripFromPath":  "..",
+    # Heavily encouraged optional argument (see docs)
+    "rootFileTitle":         "Library API",
+    # Suggested optional arguments
+    "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin":    "INPUT = ../include"
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/environment.yml

@@ -3,10 +3,13 @@ channels:
   - conda-forge
 dependencies:
   - python=3.11
+  - doxygen
   - myst-parser
   - sphinx
   - sphinx-sitemap
   - pip
   - pip:
+    - breathe
+    - exhale
     - sphinxcontrib-bibtex
     - sphinx_multiversion

doc/index.rst

@@ -101,9 +101,10 @@ Please refer to the `list of contributors <https://github.com/modsim/CADET/blob/
     simulation/index
     interface/index
     .. examples/index
+    api/library_root
     CADET-Match <https://cadet.github.io/CADET-Match/master/index.html>
     license
     zbibliography
     Legal notice <https://www.fz-juelich.de/portal/EN/Service/LegalNotice/_node.html>
 
-
+.. todolist::