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>
3 years ago · 9f70bea964
parent 47bb62b875
commit 9f70bea964
6 changed files with 203 additions and 54 deletions
--- a/1
+++ b/1
@ -32,6 +32,7 @@ scipy = "*"
 sphinx = "*"
 sphinx-sitemap = "*"
 sphinx-rtd-theme = "*"
+breathe = "*"
 subprocess32 = "*"
 tenacity = "*"

--- a/Pipfile.lock
+++ b/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": {
--- 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
--- 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 @@ language = 'en'
 # 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 @@ 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,
-    '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']
--- 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
--- 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
+```