docs: setup docs for C code (#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 4c44c02ffb.

* its in the dockerfile

Co-authored-by: Willem Melching <willem.melching@gmail.com>

Pipfile

@@ -32,6 +32,7 @@ scipy = "*"
 sphinx = "*"
 sphinx-sitemap = "*"
 sphinx-rtd-theme = "*"
+breathe = "*"
 subprocess32 = "*"
 tenacity = "*"
 

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "55c06fdfc0b686b6df23c263474db29b7a3629321b97b626ce81062d5c06e128"
+            "sha256": "658c6ab1fd200a6c84b1dec7a3b15b3d01ce911a76b1201bd4495b3031eac119"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -309,7 +309,7 @@
                 "sha256:6f62d78e2f89b4500b080fe3a81690850cd254227f27f75c3a0c491a1f351ba7",
                 "sha256:e8443a5e7a020e9d7f97f1d7d9cd17c88bcb3bc7e218bf9cf5095fe550be2951"
             ],
-            "markers": "python_version < '4.0' and python_full_version >= '3.6.1'",
+            "markers": "python_full_version >= '3.6.1' and python_version < '4.0'",
             "version": "==5.10.1"
         },
         "itsdangerous": {
@@ -701,7 +701,6 @@
                 "sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
                 "sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.21"
         },
         "pycryptodome": {
@@ -943,14 +942,6 @@
             "index": "pypi",
             "version": "==1.2.2"
         },
-        "setuptools": {
-            "hashes": [
-                "sha256:5c89b1a14a67ac5f0956f1cb0aeb7d1d3f4c8ba4e4e1ab7bf1af4933f9a2f0fe",
-                "sha256:675fcebecb43c32eb930481abf907619137547f4336206e4d673180242e1a278"
-            ],
-            "markers": "python_version >= '3.7'",
-            "version": "==60.2.0"
-        },
         "six": {
             "hashes": [
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
@@ -988,7 +979,7 @@
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==0.10.2"
         },
         "tqdm": {
@@ -1004,7 +995,7 @@
                 "sha256:4ca091dea149f945ec56afb48dae714f21e8692ef22a395223bcd328961b6a0e",
                 "sha256:7f001e5ac290a0c0401508864c7ec868be4e701886d5b573a9528ed3973d9d3b"
             ],
-            "markers": "python_version < '3.10'",
+            "markers": "python_version < '3.10' and python_version < '3.10'",
             "version": "==4.0.1"
         },
         "urllib3": {
@@ -1136,6 +1127,14 @@
             "markers": "python_version >= '3.6'",
             "version": "==3.2.0"
         },
+        "breathe": {
+            "hashes": [
+                "sha256:19faef9d63c39acb3026eeaf6e6fdc5edb95334ed36fe0c627b358d6a2d5e0da",
+                "sha256:925eeff96c6640cd857e4ddeae6f75464a1d5e2e08ee56dccce4043583ae2050"
+            ],
+            "index": "pypi",
+            "version": "==4.31.0"
+        },
         "certifi": {
             "hashes": [
                 "sha256:78884e7c1d4b00ce3cea67b44566851c4343c120abd683433ce934a68ea58872",
@@ -1833,7 +1832,6 @@
                 "sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
                 "sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.21"
         },
         "pycurl": {
@@ -2082,14 +2080,6 @@
             "index": "pypi",
             "version": "==1.7.3"
         },
-        "setuptools": {
-            "hashes": [
-                "sha256:5c89b1a14a67ac5f0956f1cb0aeb7d1d3f4c8ba4e4e1ab7bf1af4933f9a2f0fe",
-                "sha256:675fcebecb43c32eb930481abf907619137547f4336206e4d673180242e1a278"
-            ],
-            "markers": "python_version >= '3.7'",
-            "version": "==60.2.0"
-        },
         "six": {
             "hashes": [
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
@@ -2205,7 +2195,7 @@
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
             "version": "==0.10.2"
         },
         "tomli": {
@@ -2221,7 +2211,7 @@
                 "sha256:4ca091dea149f945ec56afb48dae714f21e8692ef22a395223bcd328961b6a0e",
                 "sha256:7f001e5ac290a0c0401508864c7ec868be4e701886d5b573a9528ed3973d9d3b"
             ],
-            "markers": "python_version < '3.10'",
+            "markers": "python_version < '3.10' and python_version < '3.10'",
             "version": "==4.0.1"
         },
         "urllib3": {

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

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 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 @@ language = 'en'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-        'sphinx.ext.autodoc',   # Auto-generate docs
+  'sphinx.ext.autodoc',   # Auto-generate docs
-        'sphinx.ext.viewcode',  # Add view code link to modules
+  'sphinx.ext.viewcode',  # Add view code link to modules
-        'sphinx_rtd_theme',     # Read The Docs theme
+  'sphinx_rtd_theme',     # Read The Docs theme
-        'myst_parser',          # Markdown parsing
+  'myst_parser',          # Markdown parsing
-        'sphinx_sitemap',       # sitemap generation for SEO
+  'breathe',              # Doxygen C/C++ integration
+  'sphinx_sitemap',       # sitemap generation for SEO
 ]
 
 myst_html_meta = {
-   "description": "openpilot docs",
+  "description": "openpilot docs",
-   "keywords": "op, openpilot, docs, documentation",
+  "keywords": "op, openpilot, docs, documentation",
-   "robots": "all,follow",
+  "robots": "all,follow",
-   "googlebot": "index,follow,snippet,archive",
+  "googlebot": "index,follow,snippet,archive",
-   "property=og:locale": "en_US",
+  "property=og:locale": "en_US",
-   "property=og:site_name": "docs.comma.ai",
+  "property=og:site_name": "docs.comma.ai",
-   "property=og:url": "https://docs.comma.ai",
+  "property=og:url": "https://docs.comma.ai",
-   "property=og:title": "openpilot Docuemntation",
+  "property=og:title": "openpilot Docuemntation",
-   "property=og:type": "website",
+  "property=og:type": "website",
-   "property=og:image:type": "image/jpeg",
+  "property=og:image:type": "image/jpeg",
-   "property=og:image:width": "400",
+  "property=og:image:width": "400",
-   "property=og:image": "https://docs.comma.ai/_static/logo.png",
+  "property=og:image": "https://docs.comma.ai/_static/logo.png",
-   "property=og:image:url": "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:image:secure_url": "https://docs.comma.ai/_static/logo.png",
-   "property=og:description": "openpilot Documentation",
+  "property=og:description": "openpilot Documentation",
-   "property=twitter:card": "summary_large_image",
+  "property=twitter:card": "summary_large_image",
-   "property=twitter:logo": "https://docs.comma.ai/_static/logo.png",
+  "property=twitter:logo": "https://docs.comma.ai/_static/logo.png",
-   "property=twitter:title": "openpilot Documentation",
+  "property=twitter:title": "openpilot Documentation",
-   "property=twitter:description": "openpilot Documentation"
+  "property=twitter:description": "openpilot Documentation"
 }
 
 html_baseurl = 'https://docs.comma.ai/'
@@ -78,6 +82,47 @@ templates_path = ['_templates']
 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_static_path = ['_static']
 html_logo = '_static/logo.png'
 html_favicon = '_static/favicon.ico'
 html_theme_options = {
-    'logo_only': False,
+  'logo_only': False,
-    'display_version': True,
+  'display_version': True,
-    'vcs_pageview_mode': 'blob',
+  'vcs_pageview_mode': 'blob',
-    'style_nav_header_background': '#000000',
+  'style_nav_header_background': '#000000',
 }
 html_extra_path = ['_static']

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

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
+```