zephyr/doc/conf.py
Benjamin Cabé f2b080b5d6 doc: Set default language for syntax highlighting to "none"
Force code blocks with no 'language' explicitly set to render with no
highlighting. The current default was to use python (bad), and there
would also be an option to set it to "guess" but this doesn't work all
so well (ex. some C blocks would be detected as Transact-SQL!).

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
2023-10-23 14:32:39 +02:00

342 lines
10 KiB
Python

# 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.vcs_link",
"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/"),
("3.3.0", "/3.3.0/"),
("2.7.5 (LTS)", "/2.7.5/"),
),
"display_vcs_link": 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(),
"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.vcs_link ------------------------------------------
vcs_link_version = f"v{version}" if is_release else "main"
vcs_link_base_url = f"https://github.com/zephyrproject-rtos/zephyr/blob/{vcs_link_version}"
vcs_link_prefixes = {
"samples/.*": "",
"boards/.*": "",
"snippets/.*": "",
".*": "doc",
}
vcs_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")