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
parent
47bb62b875
commit
9f70bea964
1
Pipfile
1
Pipfile
|
@ -32,6 +32,7 @@ scipy = "*"
|
||||||
sphinx = "*"
|
sphinx = "*"
|
||||||
sphinx-sitemap = "*"
|
sphinx-sitemap = "*"
|
||||||
sphinx-rtd-theme = "*"
|
sphinx-rtd-theme = "*"
|
||||||
|
breathe = "*"
|
||||||
subprocess32 = "*"
|
subprocess32 = "*"
|
||||||
tenacity = "*"
|
tenacity = "*"
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
{
|
{
|
||||||
"_meta": {
|
"_meta": {
|
||||||
"hash": {
|
"hash": {
|
||||||
"sha256": "55c06fdfc0b686b6df23c263474db29b7a3629321b97b626ce81062d5c06e128"
|
"sha256": "658c6ab1fd200a6c84b1dec7a3b15b3d01ce911a76b1201bd4495b3031eac119"
|
||||||
},
|
},
|
||||||
"pipfile-spec": 6,
|
"pipfile-spec": 6,
|
||||||
"requires": {
|
"requires": {
|
||||||
|
@ -309,7 +309,7 @@
|
||||||
"sha256:6f62d78e2f89b4500b080fe3a81690850cd254227f27f75c3a0c491a1f351ba7",
|
"sha256:6f62d78e2f89b4500b080fe3a81690850cd254227f27f75c3a0c491a1f351ba7",
|
||||||
"sha256:e8443a5e7a020e9d7f97f1d7d9cd17c88bcb3bc7e218bf9cf5095fe550be2951"
|
"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"
|
"version": "==5.10.1"
|
||||||
},
|
},
|
||||||
"itsdangerous": {
|
"itsdangerous": {
|
||||||
|
@ -701,7 +701,6 @@
|
||||||
"sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
|
"sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
|
||||||
"sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
|
"sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
|
||||||
],
|
],
|
||||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
|
||||||
"version": "==2.21"
|
"version": "==2.21"
|
||||||
},
|
},
|
||||||
"pycryptodome": {
|
"pycryptodome": {
|
||||||
|
@ -943,14 +942,6 @@
|
||||||
"index": "pypi",
|
"index": "pypi",
|
||||||
"version": "==1.2.2"
|
"version": "==1.2.2"
|
||||||
},
|
},
|
||||||
"setuptools": {
|
|
||||||
"hashes": [
|
|
||||||
"sha256:5c89b1a14a67ac5f0956f1cb0aeb7d1d3f4c8ba4e4e1ab7bf1af4933f9a2f0fe",
|
|
||||||
"sha256:675fcebecb43c32eb930481abf907619137547f4336206e4d673180242e1a278"
|
|
||||||
],
|
|
||||||
"markers": "python_version >= '3.7'",
|
|
||||||
"version": "==60.2.0"
|
|
||||||
},
|
|
||||||
"six": {
|
"six": {
|
||||||
"hashes": [
|
"hashes": [
|
||||||
"sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
|
"sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
|
||||||
|
@ -988,7 +979,7 @@
|
||||||
"sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
|
"sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
|
||||||
"sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
|
"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"
|
"version": "==0.10.2"
|
||||||
},
|
},
|
||||||
"tqdm": {
|
"tqdm": {
|
||||||
|
@ -1004,7 +995,7 @@
|
||||||
"sha256:4ca091dea149f945ec56afb48dae714f21e8692ef22a395223bcd328961b6a0e",
|
"sha256:4ca091dea149f945ec56afb48dae714f21e8692ef22a395223bcd328961b6a0e",
|
||||||
"sha256:7f001e5ac290a0c0401508864c7ec868be4e701886d5b573a9528ed3973d9d3b"
|
"sha256:7f001e5ac290a0c0401508864c7ec868be4e701886d5b573a9528ed3973d9d3b"
|
||||||
],
|
],
|
||||||
"markers": "python_version < '3.10'",
|
"markers": "python_version < '3.10' and python_version < '3.10'",
|
||||||
"version": "==4.0.1"
|
"version": "==4.0.1"
|
||||||
},
|
},
|
||||||
"urllib3": {
|
"urllib3": {
|
||||||
|
@ -1136,6 +1127,14 @@
|
||||||
"markers": "python_version >= '3.6'",
|
"markers": "python_version >= '3.6'",
|
||||||
"version": "==3.2.0"
|
"version": "==3.2.0"
|
||||||
},
|
},
|
||||||
|
"breathe": {
|
||||||
|
"hashes": [
|
||||||
|
"sha256:19faef9d63c39acb3026eeaf6e6fdc5edb95334ed36fe0c627b358d6a2d5e0da",
|
||||||
|
"sha256:925eeff96c6640cd857e4ddeae6f75464a1d5e2e08ee56dccce4043583ae2050"
|
||||||
|
],
|
||||||
|
"index": "pypi",
|
||||||
|
"version": "==4.31.0"
|
||||||
|
},
|
||||||
"certifi": {
|
"certifi": {
|
||||||
"hashes": [
|
"hashes": [
|
||||||
"sha256:78884e7c1d4b00ce3cea67b44566851c4343c120abd683433ce934a68ea58872",
|
"sha256:78884e7c1d4b00ce3cea67b44566851c4343c120abd683433ce934a68ea58872",
|
||||||
|
@ -1833,7 +1832,6 @@
|
||||||
"sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
|
"sha256:8ee45429555515e1f6b185e78100aea234072576aa43ab53aefcae078162fca9",
|
||||||
"sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
|
"sha256:e644fdec12f7872f86c58ff790da456218b10f863970249516d60a5eaca77206"
|
||||||
],
|
],
|
||||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
|
||||||
"version": "==2.21"
|
"version": "==2.21"
|
||||||
},
|
},
|
||||||
"pycurl": {
|
"pycurl": {
|
||||||
|
@ -2082,14 +2080,6 @@
|
||||||
"index": "pypi",
|
"index": "pypi",
|
||||||
"version": "==1.7.3"
|
"version": "==1.7.3"
|
||||||
},
|
},
|
||||||
"setuptools": {
|
|
||||||
"hashes": [
|
|
||||||
"sha256:5c89b1a14a67ac5f0956f1cb0aeb7d1d3f4c8ba4e4e1ab7bf1af4933f9a2f0fe",
|
|
||||||
"sha256:675fcebecb43c32eb930481abf907619137547f4336206e4d673180242e1a278"
|
|
||||||
],
|
|
||||||
"markers": "python_version >= '3.7'",
|
|
||||||
"version": "==60.2.0"
|
|
||||||
},
|
|
||||||
"six": {
|
"six": {
|
||||||
"hashes": [
|
"hashes": [
|
||||||
"sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
|
"sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
|
||||||
|
@ -2205,7 +2195,7 @@
|
||||||
"sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
|
"sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
|
||||||
"sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
|
"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"
|
"version": "==0.10.2"
|
||||||
},
|
},
|
||||||
"tomli": {
|
"tomli": {
|
||||||
|
@ -2221,7 +2211,7 @@
|
||||||
"sha256:4ca091dea149f945ec56afb48dae714f21e8692ef22a395223bcd328961b6a0e",
|
"sha256:4ca091dea149f945ec56afb48dae714f21e8692ef22a395223bcd328961b6a0e",
|
||||||
"sha256:7f001e5ac290a0c0401508864c7ec868be4e701886d5b573a9528ed3973d9d3b"
|
"sha256:7f001e5ac290a0c0401508864c7ec868be4e701886d5b573a9528ed3973d9d3b"
|
||||||
],
|
],
|
||||||
"markers": "python_version < '3.10'",
|
"markers": "python_version < '3.10' and python_version < '3.10'",
|
||||||
"version": "==4.0.1"
|
"version": "==4.0.1"
|
||||||
},
|
},
|
||||||
"urllib3": {
|
"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.
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
#
|
#
|
||||||
import os
|
import os
|
||||||
|
from os.path import exists
|
||||||
import sys
|
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('.'))
|
||||||
sys.path.insert(0, os.path.abspath('..'))
|
sys.path.insert(0, os.path.abspath('..'))
|
||||||
|
|
||||||
VERSION = get_version()
|
VERSION = get_version()
|
||||||
|
|
||||||
|
|
||||||
|
@ -37,33 +40,34 @@ language = 'en'
|
||||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
# ones.
|
# ones.
|
||||||
extensions = [
|
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 = {
|
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/'
|
html_baseurl = 'https://docs.comma.ai/'
|
||||||
|
@ -78,6 +82,47 @@ templates_path = ['_templates']
|
||||||
exclude_patterns = []
|
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 -------------------------------------------------
|
# -- Options for HTML output -------------------------------------------------
|
||||||
|
|
||||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
# 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_logo = '_static/logo.png'
|
||||||
html_favicon = '_static/favicon.ico'
|
html_favicon = '_static/favicon.ico'
|
||||||
html_theme_options = {
|
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']
|
html_extra_path = ['_static']
|
||||||
|
|
|
@ -34,6 +34,7 @@ COPY ./*.md ${OPENPILOT_PATH}/
|
||||||
|
|
||||||
RUN scons -j$(nproc)
|
RUN scons -j$(nproc)
|
||||||
|
|
||||||
|
RUN apt update && apt install doxygen -y
|
||||||
COPY ./docs ${OPENPILOT_PATH}/docs
|
COPY ./docs ${OPENPILOT_PATH}/docs
|
||||||
RUN git init .
|
RUN git init .
|
||||||
WORKDIR ${OPENPILOT_PATH}/docs
|
WORKDIR ${OPENPILOT_PATH}/docs
|
||||||
|
|
|
@ -28,8 +28,15 @@ overview.rst
|
||||||
- {ref}`search`
|
- {ref}`search`
|
||||||
|
|
||||||
```{toctree}
|
```{toctree}
|
||||||
:caption: 'Modules'
|
:caption: 'Python API'
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
modules.rst
|
modules.rst
|
||||||
```
|
```
|
||||||
|
|
||||||
|
```{toctree}
|
||||||
|
:caption: 'C/C++ API'
|
||||||
|
:maxdepth: 4
|
||||||
|
|
||||||
|
c_docs.rst
|
||||||
|
```
|
Loading…
Reference in New Issue