Skip to content

Commit 9f70bea

Browse files
tecandrewpd0wm
tecandrew
and
pd0wm
authored
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 4c44c02ffb93b3f0bc3968f2ee1fdc64faa25608. * its in the dockerfile Co-authored-by: Willem Melching <[email protected]>
1 parent 47bb62b commit 9f70bea

File tree

6 files changed

+203
-54
lines changed

6 files changed

+203
-54
lines changed

‎Pipfile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ scipy = "*"
3232
sphinx = "*"
3333
sphinx-sitemap = "*"
3434
sphinx-rtd-theme = "*"
35+
breathe = "*"
3536
subprocess32 = "*"
3637
tenacity = "*"
3738

‎Pipfile.lock

Lines changed: 14 additions & 24 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/c_docs.rst

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
openpilot
2+
==========
3+
4+
5+
opendbc
6+
------
7+
.. autodoxygenindex::
8+
:project: opendbc_can
9+
10+
11+
cereal
12+
------
13+
14+
messaging
15+
^^^^^^^^^
16+
.. autodoxygenindex::
17+
:project: cereal_messaging
18+
19+
visionipc
20+
^^^^^^^^^
21+
.. autodoxygenindex::
22+
:project: cereal_visionipc
23+
24+
25+
selfdrive
26+
---------
27+
28+
camerad
29+
^^^^^^^
30+
.. autodoxygenindex::
31+
:project: selfdrive_camerad_cameras
32+
.. autodoxygenindex::
33+
:project: selfdrive_camerad_transforms
34+
.. autodoxygenindex::
35+
:project: selfdrive_camerad_imgproc
36+
37+
locationd
38+
^^^^^^^^^
39+
.. autodoxygenindex::
40+
:project: selfdrive_locationd
41+
42+
ui
43+
^^
44+
45+
.. autodoxygenindex::
46+
:project: selfdrive_ui
47+
48+
soundd
49+
""""""
50+
.. autodoxygenindex::
51+
:project: selfdrive_ui_soundd
52+
53+
navd
54+
""""
55+
.. autodoxygenindex::
56+
:project: selfdrive_ui_navd
57+
58+
replay
59+
""""""
60+
.. autodoxygenindex::
61+
:project: selfdrive_ui_replay
62+
63+
qt
64+
""
65+
.. autodoxygenindex::
66+
:project: selfdrive_ui_qt_offroad
67+
.. autodoxygenindex::
68+
:project: selfdrive_ui_qt_maps
69+
70+
proclogd
71+
^^^^^^^^
72+
.. autodoxygenindex::
73+
:project: selfdrive_proclogd
74+
75+
modeld
76+
^^^^^^
77+
.. autodoxygenindex::
78+
:project: selfdrive_modeld_transforms
79+
.. autodoxygenindex::
80+
:project: selfdrive_modeld_models
81+
.. autodoxygenindex::
82+
:project: selfdrive_modeld_thneed
83+
.. autodoxygenindex::
84+
:project: selfdrive_modeld_runners
85+
86+
common
87+
^^^^^^
88+
.. autodoxygenindex::
89+
:project: selfdrive_common
90+
91+
sensorsd
92+
^^^^^^^^
93+
.. autodoxygenindex::
94+
:project: selfdrive_sensord_sensors
95+
96+
boardd
97+
^^^^^^
98+
.. autodoxygenindex::
99+
:project: selfdrive_boardd
100+
101+
102+
rednose
103+
-------
104+
.. autodoxygenindex::
105+
:project: rednose_repo_rednose_helpers

‎docs/conf.py

Lines changed: 74 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,13 @@
1414
# documentation root, use os.path.abspath to make it absolute, like shown here.
1515
#
1616
import os
17+
from os.path import exists
1718
import sys
18-
from selfdrive.version import get_version
19+
from selfdrive.version import get_version
20+
from common.basedir import BASEDIR
1921
sys.path.insert(0, os.path.abspath('.'))
2022
sys.path.insert(0, os.path.abspath('..'))
23+
2124
VERSION = get_version()
2225

2326

@@ -37,33 +40,34 @@
3740
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3841
# ones.
3942
extensions = [
40-
'sphinx.ext.autodoc', # Auto-generate docs
41-
'sphinx.ext.viewcode', # Add view code link to modules
42-
'sphinx_rtd_theme', # Read The Docs theme
43-
'myst_parser', # Markdown parsing
44-
'sphinx_sitemap', # sitemap generation for SEO
43+
'sphinx.ext.autodoc', # Auto-generate docs
44+
'sphinx.ext.viewcode', # Add view code link to modules
45+
'sphinx_rtd_theme', # Read The Docs theme
46+
'myst_parser', # Markdown parsing
47+
'breathe', # Doxygen C/C++ integration
48+
'sphinx_sitemap', # sitemap generation for SEO
4549
]
4650

4751
myst_html_meta = {
48-
"description": "openpilot docs",
49-
"keywords": "op, openpilot, docs, documentation",
50-
"robots": "all,follow",
51-
"googlebot": "index,follow,snippet,archive",
52-
"property=og:locale": "en_US",
53-
"property=og:site_name": "docs.comma.ai",
54-
"property=og:url": "https://docs.comma.ai",
55-
"property=og:title": "openpilot Docuemntation",
56-
"property=og:type": "website",
57-
"property=og:image:type": "image/jpeg",
58-
"property=og:image:width": "400",
59-
"property=og:image": "https://docs.comma.ai/_static/logo.png",
60-
"property=og:image:url": "https://docs.comma.ai/_static/logo.png",
61-
"property=og:image:secure_url": "https://docs.comma.ai/_static/logo.png",
62-
"property=og:description": "openpilot Documentation",
63-
"property=twitter:card": "summary_large_image",
64-
"property=twitter:logo": "https://docs.comma.ai/_static/logo.png",
65-
"property=twitter:title": "openpilot Documentation",
66-
"property=twitter:description": "openpilot Documentation"
52+
"description": "openpilot docs",
53+
"keywords": "op, openpilot, docs, documentation",
54+
"robots": "all,follow",
55+
"googlebot": "index,follow,snippet,archive",
56+
"property=og:locale": "en_US",
57+
"property=og:site_name": "docs.comma.ai",
58+
"property=og:url": "https://docs.comma.ai",
59+
"property=og:title": "openpilot Docuemntation",
60+
"property=og:type": "website",
61+
"property=og:image:type": "image/jpeg",
62+
"property=og:image:width": "400",
63+
"property=og:image": "https://docs.comma.ai/_static/logo.png",
64+
"property=og:image:url": "https://docs.comma.ai/_static/logo.png",
65+
"property=og:image:secure_url": "https://docs.comma.ai/_static/logo.png",
66+
"property=og:description": "openpilot Documentation",
67+
"property=twitter:card": "summary_large_image",
68+
"property=twitter:logo": "https://docs.comma.ai/_static/logo.png",
69+
"property=twitter:title": "openpilot Documentation",
70+
"property=twitter:description": "openpilot Documentation"
6771
}
6872

6973
html_baseurl = 'https://docs.comma.ai/'
@@ -78,6 +82,47 @@
7882
exclude_patterns = []
7983

8084

85+
# -- c docs configuration ---------------------------------------------------
86+
87+
# Breathe Configuration
88+
# breathe_default_project = "c_docs"
89+
breathe_build_directory = f"{BASEDIR}/build/docs/html/xml"
90+
breathe_separate_member_pages = True
91+
breathe_default_members = ('members', 'private-members', 'undoc-members')
92+
breathe_domain_by_extension = {
93+
"h": "cc",
94+
}
95+
breathe_implementation_filename_extensions = ['.c', '.cc']
96+
breathe_doxygen_config_options = {}
97+
breathe_projects_source = {}
98+
99+
# only document files that have accompanying .cc files next to them
100+
print("searching for c_docs...")
101+
for root, dirs, files in os.walk(BASEDIR):
102+
found = False
103+
breath_src = {}
104+
breathe_srcs_list = []
105+
106+
for file in files:
107+
ccFile = os.path.join(root, file)[:-2] + ".cc"
108+
109+
if file.endswith(".h") and exists(ccFile):
110+
f = os.path.join(root, file)
111+
112+
parent_dir_abs = os.path.dirname(f)
113+
parent_dir = parent_dir_abs[len(BASEDIR) + 1:]
114+
project = parent_dir.replace('/', '_')
115+
print(f"\tFOUND: {f} in {project}")
116+
117+
breathe_srcs_list.append(file)
118+
found = True
119+
120+
if found:
121+
breath_src[project] = (parent_dir_abs, breathe_srcs_list)
122+
breathe_projects_source.update(breath_src)
123+
124+
print(f"breathe_projects_source: {breathe_projects_source.keys()}")
125+
81126
# -- Options for HTML output -------------------------------------------------
82127

83128
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -93,9 +138,9 @@
93138
html_logo = '_static/logo.png'
94139
html_favicon = '_static/favicon.ico'
95140
html_theme_options = {
96-
'logo_only': False,
97-
'display_version': True,
98-
'vcs_pageview_mode': 'blob',
99-
'style_nav_header_background': '#000000',
141+
'logo_only': False,
142+
'display_version': True,
143+
'vcs_pageview_mode': 'blob',
144+
'style_nav_header_background': '#000000',
100145
}
101146
html_extra_path = ['_static']

‎docs/docker/Dockerfile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ COPY ./*.md ${OPENPILOT_PATH}/
3434

3535
RUN scons -j$(nproc)
3636

37+
RUN apt update && apt install doxygen -y
3738
COPY ./docs ${OPENPILOT_PATH}/docs
3839
RUN git init .
3940
WORKDIR ${OPENPILOT_PATH}/docs

‎docs/index.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,15 @@ overview.rst
2828
- {ref}`search`
2929

3030
```{toctree}
31-
:caption: 'Modules'
31+
:caption: 'Python API'
3232
:maxdepth: 2
3333
3434
modules.rst
3535
```
36+
37+
```{toctree}
38+
:caption: 'C/C++ API'
39+
:maxdepth: 4
40+
41+
c_docs.rst
42+
```

0 commit comments

Comments
 (0)