From 830b8692c05c2dbbb027bec3488f28f73ee61795 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 old-commit-hash: 9f70bea964e2037c550678581eb1363e4c99b763 --- Pipfile | 4 +- Pipfile.lock | 4 +- docs/c_docs.rst | 105 +++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 103 ++++++++++++++++++++++++++++------------ docs/docker/Dockerfile | 1 + docs/index.md | 9 +++- 6 files changed, 192 insertions(+), 34 deletions(-) create mode 100644 docs/c_docs.rst diff --git a/Pipfile b/Pipfile index e5713bc8b7..ccf05dea30 100644 --- a/Pipfile +++ b/Pipfile @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:41a4d986dd7b786f56c8b76a84b897e394b390647272153c20db1ad3f1db531c -size 1268 +oid sha256:4a3baa202ee29371a3168613072d612a3239f368c0e9122a31b398f7db0eb7b6 +size 1282 diff --git a/Pipfile.lock b/Pipfile.lock index 92fa0ccdc8..b1efbaef18 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:cffe2ec3c20be1cef17765fd41ddd7e72a3bc6375599b7df2978e652b2f6d1d2 -size 143747 +oid sha256:5aa6aaa2866c3bf2002532ac131e4dce9581adc1e8d3422dc37bba163e5fc874 +size 143236 diff --git a/docs/c_docs.rst b/docs/c_docs.rst new file mode 100644 index 0000000000..6cf5f268c5 --- /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 dfab59988f..36bfe0142a 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 3444e31a61..124feb1bfc 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 5a171ae91d..0fb2617a5b 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