doc/conf.py - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 # Zephyr documentation build configuration file.
 # Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html

 import sys
 import os
 from pathlib import Path
 import re
 import textwrap

 from sphinx.cmd.build import get_parser
 import sphinx_rtd_theme


 args = get_parser().parse_args()
 ZEPHYR_BASE = Path(__file__).resolve().parents[1]
 ZEPHYR_BUILD = Path(args.outputdir).resolve()

 # Add the '_extensions' directory to sys.path, to enable finding Sphinx
 # extensions within.
 sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_extensions"))

 # Add the '_scripts' directory to sys.path, to enable finding utility
 # modules.
 sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_scripts"))

 # Add the directory which contains the runners package as well,
 # for autodoc directives on runners.xyz.
 sys.path.insert(0, str(ZEPHYR_BASE / "scripts" / "west_commands"))

 import redirects

 try:
     import west as west_found
 except ImportError:
     west_found = False

 # -- Project --------------------------------------------------------------

 project = "Zephyr Project"
 copyright = "2015-2023 Zephyr Project members and individual contributors"
 author = "The Zephyr Project Contributors"

 # parse version from 'VERSION' file
 with open(ZEPHYR_BASE / "VERSION") as f:
     m = re.match(
         (
             r"^VERSION_MAJOR\s*=\s*(\d+)$\n"
             + r"^VERSION_MINOR\s*=\s*(\d+)$\n"
             + r"^PATCHLEVEL\s*=\s*(\d+)$\n"
             + r"^VERSION_TWEAK\s*=\s*\d+$\n"
             + r"^EXTRAVERSION\s*=\s*(.*)$"
         ),
         f.read(),
         re.MULTILINE,
     )

     if not m:
         sys.stderr.write("Warning: Could not extract kernel version\n")
         version = "Unknown"
     else:
         major, minor, patch, extra = m.groups(1)
         version = ".".join((major, minor, patch))
         if extra:
             version += "-" + extra

 release = version

 # -- General configuration ------------------------------------------------

 extensions = [
     "breathe",
     "sphinx.ext.todo",
     "sphinx.ext.extlinks",
     "sphinx.ext.autodoc",
     "sphinx.ext.graphviz",
     "sphinxcontrib.jquery",
     "zephyr.application",
     "zephyr.html_redirects",
     "zephyr.kconfig",
     "zephyr.dtcompatible-role",
     "zephyr.link-roles",
     "sphinx_tabs.tabs",
     "zephyr.warnings_filter",
     "zephyr.doxyrunner",
     "zephyr.gh_utils",
     "zephyr.manifest_projects_table",
     "notfound.extension",
     "sphinx_copybutton",
     "sphinx_togglebutton",
     "zephyr.external_content",
     "zephyr.domain",
 ]

 # Only use SVG converter when it is really needed, e.g. LaTeX.
 if tags.has("svgconvert"):  # pylint: disable=undefined-variable
     extensions.append("sphinxcontrib.rsvgconverter")

 templates_path = ["_templates"]

 exclude_patterns = ["_build"]

 if not west_found:
     exclude_patterns.append("**/*west-apis*")
 else:
     exclude_patterns.append("**/*west-not-found*")

 pygments_style = "sphinx"
 highlight_language = "none"

 todo_include_todos = False

 nitpick_ignore = [
     # ignore C standard identifiers (they are not defined in Zephyr docs)
     ("c:identifier", "FILE"),
     ("c:identifier", "int8_t"),
     ("c:identifier", "int16_t"),
     ("c:identifier", "int32_t"),
     ("c:identifier", "int64_t"),
     ("c:identifier", "intptr_t"),
     ("c:identifier", "off_t"),
     ("c:identifier", "size_t"),
     ("c:identifier", "ssize_t"),
     ("c:identifier", "time_t"),
     ("c:identifier", "uint8_t"),
     ("c:identifier", "uint16_t"),
     ("c:identifier", "uint32_t"),
     ("c:identifier", "uint64_t"),
     ("c:identifier", "uintptr_t"),
     ("c:identifier", "va_list"),
 ]

 rst_epilog = """
 .. include:: /substitutions.txt
 """

 # -- Options for HTML output ----------------------------------------------

 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_theme_options = {
     "logo_only": True,
     "prev_next_buttons_location": None
 }
 html_baseurl = "https://docs.zephyrproject.org/latest/"
 html_title = "Zephyr Project Documentation"
 html_logo = str(ZEPHYR_BASE / "doc" / "_static" / "images" / "logo.svg")
 html_favicon = str(ZEPHYR_BASE / "doc" / "_static" / "images" / "favicon.png")
 html_static_path = [str(ZEPHYR_BASE / "doc" / "_static")]
 html_last_updated_fmt = "%b %d, %Y"
 html_domain_indices = False
 html_split_index = True
 html_show_sourcelink = False
 html_show_sphinx = False
 html_search_scorer = str(ZEPHYR_BASE / "doc" / "_static" / "js" / "scorer.js")

 is_release = tags.has("release")  # pylint: disable=undefined-variable
 reference_prefix = ""
 if tags.has("publish"):  # pylint: disable=undefined-variable
     reference_prefix = f"/{version}" if is_release else "/latest"
 docs_title = "Docs / {}".format(version if is_release else "Latest")
 html_context = {
     "show_license": True,
     "docs_title": docs_title,
     "is_release": is_release,
     "current_version": version,
     "versions": (
         ("latest", "/"),
         ("3.5.0", "/3.5.0/"),
         ("3.4.0", "/3.4.0/"),
         ("2.7.5 (LTS)", "/2.7.5/"),
     ),
     "display_gh_links": True,
     "reference_links": {
         "API": f"{reference_prefix}/doxygen/html/index.html",
         "Kconfig Options": f"{reference_prefix}/kconfig.html",
         "Devicetree Bindings": f"{reference_prefix}/build/dts/api/bindings.html",
         "West Projects": f"{reference_prefix}/develop/manifest/index.html",
     }
 }

 # -- Options for LaTeX output ---------------------------------------------

 latex_elements = {
     "papersize": "a4paper",
     "maketitle": open(ZEPHYR_BASE / "doc" / "_static" / "latex" / "title.tex").read(),
     "preamble": open(ZEPHYR_BASE / "doc" / "_static" / "latex" / "preamble.tex").read(),
     "makeindex": r"\usepackage[columns=1]{idxlayout}\makeindex",
     "fontpkg": textwrap.dedent(r"""
                                     \usepackage{noto}
                                     \usepackage{inconsolata-nerd-font}
                                     \usepackage[T1]{fontenc}
                                 """),
     "sphinxsetup": ",".join(
         (
             # NOTE: colors match those found in light.css stylesheet
             "verbatimwithframe=false",
             "VerbatimColor={HTML}{f0f2f4}",
             "InnerLinkColor={HTML}{2980b9}",
             "warningBgColor={HTML}{e9a499}",
             "warningborder=0pt",
             r"HeaderFamily=\rmfamily\bfseries",
         )
     ),
 }
 latex_logo = str(ZEPHYR_BASE / "doc" / "_static" / "images" / "logo-latex.pdf")
 latex_documents = [
     ("index-tex", "zephyr.tex", "Zephyr Project Documentation", author, "manual"),
 ]
 latex_engine = "xelatex"

 # -- Options for zephyr.doxyrunner plugin ---------------------------------

 doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen")
 doxyrunner_doxyfile = ZEPHYR_BASE / "doc" / "zephyr.doxyfile.in"
 doxyrunner_outdir = ZEPHYR_BUILD / "doxygen"
 doxyrunner_fmt = True
 doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version}
 doxyrunner_outdir_var = "DOXY_OUT"

 # -- Options for Breathe plugin -------------------------------------------

 breathe_projects = {"Zephyr": str(doxyrunner_outdir / "xml")}
 breathe_default_project = "Zephyr"
 breathe_domain_by_extension = {
     "h": "c",
     "c": "c",
 }
 breathe_show_enumvalue_initializer = True
 breathe_default_members = ("members", )

 cpp_id_attributes = [
     "__syscall",
     "__syscall_always_inline",
     "__deprecated",
     "__may_alias",
     "__used",
     "__unused",
     "__weak",
     "__attribute_const__",
     "__DEPRECATED_MACRO",
     "FUNC_NORETURN",
     "__subsystem",
     "ALWAYS_INLINE",
 ]
 c_id_attributes = cpp_id_attributes

 # -- Options for html_redirect plugin -------------------------------------

 html_redirect_pages = redirects.REDIRECTS

 # -- Options for zephyr.warnings_filter -----------------------------------

 warnings_filter_config = str(ZEPHYR_BASE / "doc" / "known-warnings.txt")

 # -- Options for zephyr.link-roles ----------------------------------------

 link_roles_manifest_project = "zephyr"
 link_roles_manifest_baseurl = "https://github.com/zephyrproject-rtos/zephyr"

 # -- Options for notfound.extension ---------------------------------------

 notfound_urls_prefix = f"/{version}/" if is_release else "/latest/"

 # -- Options for zephyr.gh_utils ------------------------------------------

 gh_link_version = f"v{version}" if is_release else "main"
 gh_link_base_url = f"https://github.com/zephyrproject-rtos/zephyr"
 gh_link_prefixes = {
     "samples/.*": "",
     "boards/.*": "",
     "snippets/.*": "",
     ".*": "doc",
 }
 gh_link_exclude = [
     "reference/kconfig.*",
     "build/dts/api/bindings.*",
     "build/dts/api/compatibles.*",
 ]

 # -- Options for zephyr.kconfig -------------------------------------------

 kconfig_generate_db = True
 kconfig_ext_paths = [ZEPHYR_BASE]

 # -- Options for zephyr.external_content ----------------------------------

 external_content_contents = [
     (ZEPHYR_BASE / "doc", "[!_]*"),
     (ZEPHYR_BASE, "boards/**/*.rst"),
     (ZEPHYR_BASE, "boards/**/doc"),
     (ZEPHYR_BASE, "samples/**/*.html"),
     (ZEPHYR_BASE, "samples/**/*.rst"),
     (ZEPHYR_BASE, "samples/**/doc"),
     (ZEPHYR_BASE, "snippets/**/*.rst"),
     (ZEPHYR_BASE, "snippets/**/doc"),
 ]
 external_content_keep = [
     "reference/kconfig/*",
     "develop/manifest/index.rst",
     "build/dts/api/bindings.rst",
     "build/dts/api/bindings/**/*",
     "build/dts/api/compatibles/**/*",
 ]

 # -- Options for sphinx.ext.graphviz --------------------------------------

 graphviz_dot = os.environ.get("DOT_EXECUTABLE", "dot")
 graphviz_output_format = "svg"
 graphviz_dot_args = [
     "-Gbgcolor=transparent",
     "-Nstyle=filled",
     "-Nfillcolor=white",
     "-Ncolor=gray60",
     "-Nfontcolor=gray25",
     "-Ecolor=gray60",
 ]

 # -- Options for sphinx_copybutton ----------------------------------------

 copybutton_prompt_text = r"\$ |uart:~\$ "
 copybutton_prompt_is_regexp = True

 # -- Linkcheck options ----------------------------------------------------

 linkcheck_ignore = [
     r"https://github.com/zephyrproject-rtos/zephyr/issues/.*"
 ]

 extlinks = {
     "github": ("https://github.com/zephyrproject-rtos/zephyr/issues/%s", "GitHub #%s"),
 }

 linkcheck_timeout = 30
 linkcheck_workers = 10
 linkcheck_anchors = False


 def setup(app):
     # theme customizations
     app.add_css_file("css/custom.css")
     app.add_js_file("js/dark-mode-toggle.min.mjs", type="module")
	# Zephyr documentation build configuration file.
	# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html

	import sys
	import os
	from pathlib import Path
	import re
	import textwrap

	from sphinx.cmd.build import get_parser
	import sphinx_rtd_theme


	args = get_parser().parse_args()
	ZEPHYR_BASE = Path(__file__).resolve().parents[1]
	ZEPHYR_BUILD = Path(args.outputdir).resolve()

	# Add the '_extensions' directory to sys.path, to enable finding Sphinx
	# extensions within.
	sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_extensions"))

	# Add the '_scripts' directory to sys.path, to enable finding utility
	# modules.
	sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_scripts"))

	# Add the directory which contains the runners package as well,
	# for autodoc directives on runners.xyz.
	sys.path.insert(0, str(ZEPHYR_BASE / "scripts" / "west_commands"))

	import redirects

	try:
	import west as west_found
	except ImportError:
	west_found = False

	# -- Project --------------------------------------------------------------

	project = "Zephyr Project"
	copyright = "2015-2023 Zephyr Project members and individual contributors"
	author = "The Zephyr Project Contributors"

	# parse version from 'VERSION' file
	with open(ZEPHYR_BASE / "VERSION") as f:
	m = re.match(
	(
	r"^VERSION_MAJOR\s=\s(\d+)$\n"
	+ r"^VERSION_MINOR\s=\s(\d+)$\n"
	+ r"^PATCHLEVEL\s=\s(\d+)$\n"
	+ r"^VERSION_TWEAK\s=\s\d+$\n"
	+ r"^EXTRAVERSION\s=\s(.*)$"
	),
	f.read(),
	re.MULTILINE,
	)

	if not m:
	sys.stderr.write("Warning: Could not extract kernel version\n")
	version = "Unknown"
	else:
	major, minor, patch, extra = m.groups(1)
	version = ".".join((major, minor, patch))
	if extra:
	version += "-" + extra

	release = version

	# -- General configuration ------------------------------------------------

	extensions = [
	"breathe",
	"sphinx.ext.todo",
	"sphinx.ext.extlinks",
	"sphinx.ext.autodoc",
	"sphinx.ext.graphviz",
	"sphinxcontrib.jquery",
	"zephyr.application",
	"zephyr.html_redirects",
	"zephyr.kconfig",
	"zephyr.dtcompatible-role",
	"zephyr.link-roles",
	"sphinx_tabs.tabs",
	"zephyr.warnings_filter",
	"zephyr.doxyrunner",
	"zephyr.gh_utils",
	"zephyr.manifest_projects_table",
	"notfound.extension",
	"sphinx_copybutton",
	"sphinx_togglebutton",
	"zephyr.external_content",
	"zephyr.domain",
	]

	# Only use SVG converter when it is really needed, e.g. LaTeX.
	if tags.has("svgconvert"): # pylint: disable=undefined-variable
	extensions.append("sphinxcontrib.rsvgconverter")

	templates_path = ["_templates"]

	exclude_patterns = ["_build"]

	if not west_found:
	exclude_patterns.append("*/west-apis*")
	else:
	exclude_patterns.append("*/west-not-found*")

	pygments_style = "sphinx"
	highlight_language = "none"

	todo_include_todos = False

	nitpick_ignore = [
	# ignore C standard identifiers (they are not defined in Zephyr docs)
	("c:identifier", "FILE"),
	("c:identifier", "int8_t"),
	("c:identifier", "int16_t"),
	("c:identifier", "int32_t"),
	("c:identifier", "int64_t"),
	("c:identifier", "intptr_t"),
	("c:identifier", "off_t"),
	("c:identifier", "size_t"),
	("c:identifier", "ssize_t"),
	("c:identifier", "time_t"),
	("c:identifier", "uint8_t"),
	("c:identifier", "uint16_t"),
	("c:identifier", "uint32_t"),
	("c:identifier", "uint64_t"),
	("c:identifier", "uintptr_t"),
	("c:identifier", "va_list"),
	]

	rst_epilog = """
	.. include:: /substitutions.txt
	"""

	# -- Options for HTML output ----------------------------------------------

	html_theme = "sphinx_rtd_theme"
	html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
	html_theme_options = {
	"logo_only": True,
	"prev_next_buttons_location": None
	}
	html_baseurl = "https://docs.zephyrproject.org/latest/"
	html_title = "Zephyr Project Documentation"
	html_logo = str(ZEPHYR_BASE / "doc" / "_static" / "images" / "logo.svg")
	html_favicon = str(ZEPHYR_BASE / "doc" / "_static" / "images" / "favicon.png")
	html_static_path = [str(ZEPHYR_BASE / "doc" / "_static")]
	html_last_updated_fmt = "%b %d, %Y"
	html_domain_indices = False
	html_split_index = True
	html_show_sourcelink = False
	html_show_sphinx = False
	html_search_scorer = str(ZEPHYR_BASE / "doc" / "_static" / "js" / "scorer.js")

	is_release = tags.has("release") # pylint: disable=undefined-variable
	reference_prefix = ""
	if tags.has("publish"): # pylint: disable=undefined-variable
	reference_prefix = f"/{version}" if is_release else "/latest"
	docs_title = "Docs / {}".format(version if is_release else "Latest")
	html_context = {
	"show_license": True,
	"docs_title": docs_title,
	"is_release": is_release,
	"current_version": version,
	"versions": (
	("latest", "/"),
	("3.5.0", "/3.5.0/"),
	("3.4.0", "/3.4.0/"),
	("2.7.5 (LTS)", "/2.7.5/"),
	),
	"display_gh_links": True,
	"reference_links": {
	"API": f"{reference_prefix}/doxygen/html/index.html",
	"Kconfig Options": f"{reference_prefix}/kconfig.html",
	"Devicetree Bindings": f"{reference_prefix}/build/dts/api/bindings.html",
	"West Projects": f"{reference_prefix}/develop/manifest/index.html",
	}
	}

	# -- Options for LaTeX output ---------------------------------------------

	latex_elements = {
	"papersize": "a4paper",
	"maketitle": open(ZEPHYR_BASE / "doc" / "_static" / "latex" / "title.tex").read(),
	"preamble": open(ZEPHYR_BASE / "doc" / "_static" / "latex" / "preamble.tex").read(),
	"makeindex": r"\usepackage[columns=1]{idxlayout}\makeindex",
	"fontpkg": textwrap.dedent(r"""
	\usepackage{noto}
	\usepackage{inconsolata-nerd-font}
	\usepackage[T1]{fontenc}
	"""),
	"sphinxsetup": ",".join(
	(
	# NOTE: colors match those found in light.css stylesheet
	"verbatimwithframe=false",
	"VerbatimColor={HTML}{f0f2f4}",
	"InnerLinkColor={HTML}{2980b9}",
	"warningBgColor={HTML}{e9a499}",
	"warningborder=0pt",
	r"HeaderFamily=\rmfamily\bfseries",
	)
	),
	}
	latex_logo = str(ZEPHYR_BASE / "doc" / "_static" / "images" / "logo-latex.pdf")
	latex_documents = [
	("index-tex", "zephyr.tex", "Zephyr Project Documentation", author, "manual"),
	]
	latex_engine = "xelatex"

	# -- Options for zephyr.doxyrunner plugin ---------------------------------

	doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen")
	doxyrunner_doxyfile = ZEPHYR_BASE / "doc" / "zephyr.doxyfile.in"
	doxyrunner_outdir = ZEPHYR_BUILD / "doxygen"
	doxyrunner_fmt = True
	doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version}
	doxyrunner_outdir_var = "DOXY_OUT"

	# -- Options for Breathe plugin -------------------------------------------

	breathe_projects = {"Zephyr": str(doxyrunner_outdir / "xml")}
	breathe_default_project = "Zephyr"
	breathe_domain_by_extension = {
	"h": "c",
	"c": "c",
	}
	breathe_show_enumvalue_initializer = True
	breathe_default_members = ("members", )

	cpp_id_attributes = [
	"__syscall",
	"__syscall_always_inline",
	"__deprecated",
	"__may_alias",
	"__used",
	"__unused",
	"__weak",
	"__attribute_const__",
	"__DEPRECATED_MACRO",
	"FUNC_NORETURN",
	"__subsystem",
	"ALWAYS_INLINE",
	]
	c_id_attributes = cpp_id_attributes

	# -- Options for html_redirect plugin -------------------------------------

	html_redirect_pages = redirects.REDIRECTS

	# -- Options for zephyr.warnings_filter -----------------------------------

	warnings_filter_config = str(ZEPHYR_BASE / "doc" / "known-warnings.txt")

	# -- Options for zephyr.link-roles ----------------------------------------

	link_roles_manifest_project = "zephyr"
	link_roles_manifest_baseurl = "https://github.com/zephyrproject-rtos/zephyr"

	# -- Options for notfound.extension ---------------------------------------

	notfound_urls_prefix = f"/{version}/" if is_release else "/latest/"

	# -- Options for zephyr.gh_utils ------------------------------------------

	gh_link_version = f"v{version}" if is_release else "main"
	gh_link_base_url = f"https://github.com/zephyrproject-rtos/zephyr"
	gh_link_prefixes = {
	"samples/.*": "",
	"boards/.*": "",
	"snippets/.*": "",
	".*": "doc",
	}
	gh_link_exclude = [
	"reference/kconfig.*",
	"build/dts/api/bindings.*",
	"build/dts/api/compatibles.*",
	]

	# -- Options for zephyr.kconfig -------------------------------------------

	kconfig_generate_db = True
	kconfig_ext_paths = [ZEPHYR_BASE]

	# -- Options for zephyr.external_content ----------------------------------

	external_content_contents = [
	(ZEPHYR_BASE / "doc", "[!_]*"),
	(ZEPHYR_BASE, "boards/*/.rst"),
	(ZEPHYR_BASE, "boards/**/doc"),
	(ZEPHYR_BASE, "samples/*/.html"),
	(ZEPHYR_BASE, "samples/*/.rst"),
	(ZEPHYR_BASE, "samples/**/doc"),
	(ZEPHYR_BASE, "snippets/*/.rst"),
	(ZEPHYR_BASE, "snippets/**/doc"),
	]
	external_content_keep = [
	"reference/kconfig/*",
	"develop/manifest/index.rst",
	"build/dts/api/bindings.rst",
	"build/dts/api/bindings/*/",
	"build/dts/api/compatibles/*/",
	]

	# -- Options for sphinx.ext.graphviz --------------------------------------

	graphviz_dot = os.environ.get("DOT_EXECUTABLE", "dot")
	graphviz_output_format = "svg"
	graphviz_dot_args = [
	"-Gbgcolor=transparent",
	"-Nstyle=filled",
	"-Nfillcolor=white",
	"-Ncolor=gray60",
	"-Nfontcolor=gray25",
	"-Ecolor=gray60",
	]

	# -- Options for sphinx_copybutton ----------------------------------------

	copybutton_prompt_text = r"\$ \|uart:~\$ "
	copybutton_prompt_is_regexp = True

	# -- Linkcheck options ----------------------------------------------------

	linkcheck_ignore = [
	r"https://github.com/zephyrproject-rtos/zephyr/issues/.*"
	]

	extlinks = {
	"github": ("https://github.com/zephyrproject-rtos/zephyr/issues/%s", "GitHub #%s"),
	}

	linkcheck_timeout = 30
	linkcheck_workers = 10
	linkcheck_anchors = False


	def setup(app):
	# theme customizations
	app.add_css_file("css/custom.css")
	app.add_js_file("js/dark-mode-toggle.min.mjs", type="module")