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>
pull/23400/head
Andrew
GitHub
parent
47bb62b875
commit
9f70bea964
1
Pipfile
1
Pipfile
|
|
@ -32,6 +32,7 @@ scipy = "*"
|
|||
sphinx = "*"
|
||||
sphinx-sitemap = "*"
|
||||
sphinx-rtd-theme = "*"
|
||||
breathe = "*"
|
||||
subprocess32 = "*"
|
||||
tenacity = "*"
|
||||
|
||||
|
|
|
|||
|
|
@ -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": {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
103
docs/conf.py
103
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']
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
Loading…
Reference in New Issue