docs: setup docs for C code (commaai#23262)

* add breathe and doxygen * add sphinx-breathe c docs generation * add c docs to site * built in docker * build base image first * namespace cleanup * Revert "build base image first" This reverts commit 4c44c02. * its in the dockerfile Co-authored-by: Willem Melching <willem.melching@gmail.com>
budney · Jan 4, 2022 · 9f70bea · 9f70bea
1 parent 47bb62b
commit 9f70bea
Show file tree

Hide file tree

Showing 6 changed files with 203 additions and 54 deletions.
diff --git a/Pipfile b/Pipfile
@@ -32,6 +32,7 @@ scipy = "*"
 sphinx = "*"
 sphinx-sitemap = "*"
 sphinx-rtd-theme = "*"
+breathe = "*"
 subprocess32 = "*"
 tenacity = "*"
 

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/docs/c_docs.rst b/docs/c_docs.rst
@@ -0,0 +1,105 @@
+openpilot
+==========
+
+
+opendbc
+------
+.. autodoxygenindex::
+   :project: opendbc_can
+
+
+cereal
+------
+
+messaging
+^^^^^^^^^
+.. autodoxygenindex::
+   :project: cereal_messaging
+
+visionipc
+^^^^^^^^^
+.. autodoxygenindex::
+   :project: cereal_visionipc
+
+
+selfdrive
+---------
+
+camerad
+^^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_camerad_cameras
+.. autodoxygenindex::
+   :project: selfdrive_camerad_transforms
+.. autodoxygenindex::
+   :project: selfdrive_camerad_imgproc
+
+locationd
+^^^^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_locationd
+
+ui
+^^
+
+.. autodoxygenindex::
+   :project: selfdrive_ui
+
+soundd
+""""""
+.. autodoxygenindex::
+   :project: selfdrive_ui_soundd
+
+navd
+""""
+.. autodoxygenindex::
+   :project: selfdrive_ui_navd
+
+replay
+""""""
+.. autodoxygenindex::
+   :project: selfdrive_ui_replay
+
+qt
+""
+.. autodoxygenindex::
+   :project: selfdrive_ui_qt_offroad
+.. autodoxygenindex::
+   :project: selfdrive_ui_qt_maps
+
+proclogd
+^^^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_proclogd
+
+modeld
+^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_modeld_transforms
+.. autodoxygenindex::
+   :project: selfdrive_modeld_models
+.. autodoxygenindex::
+   :project: selfdrive_modeld_thneed
+.. autodoxygenindex::
+   :project: selfdrive_modeld_runners
+
+common
+^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_common
+
+sensorsd
+^^^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_sensord_sensors
+
+boardd
+^^^^^^
+.. autodoxygenindex::
+   :project: selfdrive_boardd
+
+
+rednose
+-------
+.. autodoxygenindex::
+   :project: rednose_repo_rednose_helpers
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,10 +14,13 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+from os.path import exists
 import sys
-from selfdrive.version import get_version 
+from selfdrive.version import get_version
+from common.basedir import BASEDIR
 sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('..'))
+
 VERSION = get_version()
 
 
@@ -37,33 +40,34 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-        'sphinx.ext.autodoc',   # Auto-generate docs
-        'sphinx.ext.viewcode',  # Add view code link to modules
-        'sphinx_rtd_theme',     # Read The Docs theme
-        'myst_parser',          # Markdown parsing
-        'sphinx_sitemap',       # sitemap generation for SEO
+  'sphinx.ext.autodoc',   # Auto-generate docs
+  'sphinx.ext.viewcode',  # Add view code link to modules
+  'sphinx_rtd_theme',     # Read The Docs theme
+  'myst_parser',          # Markdown parsing
+  'breathe',              # Doxygen C/C++ integration
+  'sphinx_sitemap',       # sitemap generation for SEO
 ]
 
 myst_html_meta = {
-   "description": "openpilot docs",
-   "keywords": "op, openpilot, docs, documentation",
-   "robots": "all,follow",
-   "googlebot": "index,follow,snippet,archive",
-   "property=og:locale": "en_US",
-   "property=og:site_name": "docs.comma.ai",
-   "property=og:url": "https://docs.comma.ai",
-   "property=og:title": "openpilot Docuemntation",
-   "property=og:type": "website",
-   "property=og:image:type": "image/jpeg",
-   "property=og:image:width": "400",
-   "property=og:image": "https://docs.comma.ai/_static/logo.png",
-   "property=og:image:url": "https://docs.comma.ai/_static/logo.png",
-   "property=og:image:secure_url": "https://docs.comma.ai/_static/logo.png",
-   "property=og:description": "openpilot Documentation",
-   "property=twitter:card": "summary_large_image",
-   "property=twitter:logo": "https://docs.comma.ai/_static/logo.png",
-   "property=twitter:title": "openpilot Documentation",
-   "property=twitter:description": "openpilot Documentation"
+  "description": "openpilot docs",
+  "keywords": "op, openpilot, docs, documentation",
+  "robots": "all,follow",
+  "googlebot": "index,follow,snippet,archive",
+  "property=og:locale": "en_US",
+  "property=og:site_name": "docs.comma.ai",
+  "property=og:url": "https://docs.comma.ai",
+  "property=og:title": "openpilot Docuemntation",
+  "property=og:type": "website",
+  "property=og:image:type": "image/jpeg",
+  "property=og:image:width": "400",
+  "property=og:image": "https://docs.comma.ai/_static/logo.png",
+  "property=og:image:url": "https://docs.comma.ai/_static/logo.png",
+  "property=og:image:secure_url": "https://docs.comma.ai/_static/logo.png",
+  "property=og:description": "openpilot Documentation",
+  "property=twitter:card": "summary_large_image",
+  "property=twitter:logo": "https://docs.comma.ai/_static/logo.png",
+  "property=twitter:title": "openpilot Documentation",
+  "property=twitter:description": "openpilot Documentation"
 }
 
 html_baseurl = 'https://docs.comma.ai/'
@@ -78,6 +82,47 @@
 exclude_patterns = []
 
 
+# -- c docs configuration ---------------------------------------------------
+
+# Breathe Configuration
+# breathe_default_project = "c_docs"
+breathe_build_directory = f"{BASEDIR}/build/docs/html/xml"
+breathe_separate_member_pages = True
+breathe_default_members = ('members', 'private-members', 'undoc-members')
+breathe_domain_by_extension = {
+  "h": "cc",
+}
+breathe_implementation_filename_extensions = ['.c', '.cc']
+breathe_doxygen_config_options = {}
+breathe_projects_source = {}
+
+# only document files that have accompanying .cc files next to them
+print("searching for c_docs...")
+for root, dirs, files in os.walk(BASEDIR):
+  found = False
+  breath_src = {}
+  breathe_srcs_list = []
+
+  for file in files:
+    ccFile = os.path.join(root, file)[:-2] + ".cc"
+
+    if file.endswith(".h") and exists(ccFile):
+      f = os.path.join(root, file)
+
+      parent_dir_abs = os.path.dirname(f)
+      parent_dir = parent_dir_abs[len(BASEDIR) + 1:]
+      project = parent_dir.replace('/', '_')
+      print(f"\tFOUND: {f} in {project}")
+
+      breathe_srcs_list.append(file)
+      found = True
+
+    if found:
+      breath_src[project] = (parent_dir_abs, breathe_srcs_list)
+      breathe_projects_source.update(breath_src)
+
+print(f"breathe_projects_source: {breathe_projects_source.keys()}")
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -93,9 +138,9 @@
 html_logo = '_static/logo.png'
 html_favicon = '_static/favicon.ico'
 html_theme_options = {
-    'logo_only': False,
-    'display_version': True,
-    'vcs_pageview_mode': 'blob',
-    'style_nav_header_background': '#000000',
+  'logo_only': False,
+  'display_version': True,
+  'vcs_pageview_mode': 'blob',
+  'style_nav_header_background': '#000000',
 }
 html_extra_path = ['_static']
diff --git a/docs/docker/Dockerfile b/docs/docker/Dockerfile
@@ -34,6 +34,7 @@ COPY ./*.md ${OPENPILOT_PATH}/
 
 RUN scons -j$(nproc)
 
+RUN apt update && apt install doxygen -y
 COPY ./docs ${OPENPILOT_PATH}/docs
 RUN git init .
 WORKDIR ${OPENPILOT_PATH}/docs

diff --git a/docs/index.md b/docs/index.md
@@ -28,8 +28,15 @@ overview.rst
 - {ref}`search`
 
 ```{toctree}
-:caption: 'Modules'
+:caption: 'Python API'
 :maxdepth: 2
 
 modules.rst
 ```
+
+```{toctree}
+:caption: 'C/C++ API'
+:maxdepth: 4
+
+c_docs.rst
+```