mirror of
https://github.com/firestar5683/StarPilot.git
synced 2026-08-21 08:14:00 +08:00
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 <willem.melching@gmail.com> old-commit-hash: 9f70bea964e2037c550678581eb1363e4c99b763
This commit is contained in:
Andrew
+74
-29
@@ -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']
|
||||
|
||||
Reference in New Issue
Block a user