From 9f70bea964e2037c550678581eb1363e4c99b763 Mon Sep 17 00:00:00 2001 From: Andrew Date: Tue, 4 Jan 2022 08:26:07 -0800 Subject: [PATCH] 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 --- Pipfile | 1 + Pipfile.lock | 38 ++++++--------- docs/c_docs.rst | 105 +++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 103 ++++++++++++++++++++++++++++------------ docs/docker/Dockerfile | 1 + docs/index.md | 9 +++- 6 files changed, 203 insertions(+), 54 deletions(-) create mode 100644 docs/c_docs.rst diff --git a/Pipfile b/Pipfile index 6bb6e0a22..0ec00008b 100644 --- a/Pipfile +++ b/Pipfile @@ -32,6 +32,7 @@ scipy = "*" sphinx = "*" sphinx-sitemap = "*" sphinx-rtd-theme = "*" +breathe = "*" subprocess32 = "*" tenacity = "*" diff --git a/Pipfile.lock b/Pipfile.lock index a39be5349..15463e3e7 100644 --- 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": { diff --git a/docs/c_docs.rst b/docs/c_docs.rst new file mode 100644 index 000000000..6cf5f268c --- /dev/null +++ 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 diff --git a/docs/conf.py b/docs/conf.py index dfab59988..36bfe0142 100644 --- 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'] diff --git a/docs/docker/Dockerfile b/docs/docker/Dockerfile index 3444e31a6..124feb1bf 100644 --- 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 diff --git a/docs/index.md b/docs/index.md index 5a171ae91..0fb2617a5 100644 --- 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 +``` \ No newline at end of file