update docs

nervosys · Feb 13, 2024 · acedf3b · acedf3b
1 parent 891278a
commit acedf3b
Show file tree

Hide file tree

Showing 7 changed files with 37 additions and 13 deletions.
diff --git a/.github/workflows/test_docs.yml b/.github/workflows/test_docs.yml
@@ -30,7 +30,7 @@ jobs:
           python3 -m pip install --upgrade pip
           pip install mkdocs mkdocs-material pymdown-extensions  # mkdocstrings[python]
           pip install sphinx sphinx-immaterial numpy msgpack-rpc-python
-          pip install breathe  # for doxygen -> sphinx conversion
+          pip install breathe exhale  # for doxygen -> sphinx -> html conversion
 
       - name: "Generate C++ API documentation: Doxygen -> Breathe -> Sphinx"
         shell: bash

diff --git a/.gitignore b/.gitignore
@@ -401,6 +401,7 @@ build_docs/
 # C++ API docs
 AutonomyLib/docs/doxyxml/
 AutonomyLib/docs/_build/
+AutonomyLib/docs/api/
 
 # Python API docs
 python/docs/_build

diff --git a/AutonomyLib/docs/Doxyfile b/AutonomyLib/docs/Doxyfile
@@ -180,7 +180,9 @@ FILE_PATTERNS          = *.c \
                          *.qsf \
                          *.ice
 RECURSIVE              = YES
-EXCLUDE                =
+EXCLUDE                = ./AutonomyLib/include/common/ \
+                         ./AutonomyLib/src/common/ \
+                         ./AutonomyLib/include/sensors/imu/ImuBase.hpp
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
 EXCLUDE_SYMBOLS        =
@@ -354,7 +356,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
 ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =

diff --git a/AutonomyLib/docs/_static/css/extra.css b/AutonomyLib/docs/_static/css/extra.css
@@ -122,7 +122,7 @@ Nervosys tripartite color scheme:
     --md-default-fg-color--lighter: hsl(0, 0%, 90%);
     --md-default-fg-color--lightest: hsl(0, 0%, 10%);  /* background */
 
-    --md-primary-bg-color: hsl(0, 0%, 0%);
+    --md-primary-bg-color: hsl(0, 0%, 100%); /* header */
     --md-default-bg-color: hsl(0, 14%, 4%);
 
     /* text color shades */
@@ -161,7 +161,7 @@ Nervosys tripartite color scheme:
     --md-code-hl-variable-color:       hsl(200, 100%, 70%);
 
     /* typeset color shades */
-    /* 
+    /*
     --md-typeset-color:                hsl(0, 0%, 90%);
     --md-typeset-a-color:              hsl(0, 0%, 50%);
     */

diff --git a/AutonomyLib/docs/conf.py b/AutonomyLib/docs/conf.py
@@ -51,18 +51,21 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx_immaterial",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.doctest",
+    "sphinx.ext.duration",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.inheritance_diagram",
     "sphinx.ext.todo",
     "sphinx.ext.mathjax",
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_immaterial",
     "breathe",
+    "exhale",
 ]
 
 autodoc_default_flags = ["members"]
@@ -71,8 +74,25 @@
 autosectionlabel_maxdepth = 4
 
 # Breathe Configuration
-breathe_projects = {"AutonomyLib": "./doxyxml/xml/"}
+breathe_projects = {"AutonomyLib": "./doxyxml/xml"}
+# breathe_projects_source = {"AutonomyLib": "./doxyxml/xml"}
 breathe_default_project = "AutonomyLib"
+# breathe_default_members = ("members", "undoc-members")
+
+exhale_args = {
+    # These arguments are required
+    "containmentFolder": "./api",
+    "rootFileName": "library_root.rst",
+    "doxygenStripFromPath": "..",
+    # Heavily encouraged optional argument (see docs)
+    "rootFileTitle": "C++ Library API",
+    # Suggested optional arguments
+    "createTreeView": True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": False,
+    # "exhaleDoxygenStdin":    "INPUT = ../include"
+}
 
 # Tell sphinx what the primary language being documented is.
 primary_domain = "cpp"
@@ -183,7 +203,7 @@
         "text": "Roboto",
         "code": "Roboto Mono",
     },
-    "language": "en",
+    # "language": "en",
     "palette": [
         # {
         #     "media": "(prefers-color-scheme)",
@@ -209,7 +229,7 @@
             },
         },
     ],
-    "favicon": "media/images/rune.svg",
+    # "favicon": "media/images/rune.svg",
     "icon": {
         "logo": "material/book-open-page-variant",
         "repo": "fontawesome/brands/git-alt",

diff --git a/AutonomyLib/docs/index.rst b/AutonomyLib/docs/index.rst
@@ -4,13 +4,14 @@
    contain the root `toctree` directive.
 
 AutonomyLib
-=======================================
+===========
 
 This page documents `AutonomyLib`_, the C++ library of `AutonomySim`_.
 
 .. _`AutonomySim`: https://github.com/nervosys/AutonomySim 
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
+   about
+   api/library_root
diff --git a/python/docs/_static/css/extra.css b/python/docs/_static/css/extra.css
@@ -122,7 +122,7 @@ Nervosys tripartite color scheme:
     --md-default-fg-color--lighter: hsl(0, 0%, 90%);
     --md-default-fg-color--lightest: hsl(0, 0%, 10%);  /* background */
 
-    --md-primary-bg-color: hsl(0, 0%, 0%);
+    --md-primary-bg-color: hsl(0, 0%, 100%); /* header */
     --md-default-bg-color: hsl(0, 14%, 4%);
 
     /* text color shades */
@@ -161,7 +161,7 @@ Nervosys tripartite color scheme:
     --md-code-hl-variable-color:       hsl(200, 100%, 70%);
 
     /* typeset color shades */
-    /* 
+    /*
     --md-typeset-color:                hsl(0, 0%, 90%);
     --md-typeset-a-color:              hsl(0, 0%, 50%);
     */