# 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 ZEPHYR_BASE = Path(__file__).resolve().parents[1] ZEPHYR_BUILD = Path(os.environ.get("OUTPUT_DIR")).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")) # Add the directory which contains the pytest-twister-pytest sys.path.insert(0, str(ZEPHYR_BASE / "scripts" / "pylib" / "pytest-twister-harness" / "src")) import redirects try: import west as west_found except ImportError: west_found = False # -- Project -------------------------------------------------------------- project = "Zephyr Project" copyright = "2015-2024 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 # parse SDK version from 'SDK_VERSION' file with open(ZEPHYR_BASE / "SDK_VERSION") as f: sdk_version = f.read().strip() # -- General configuration ------------------------------------------------ extensions = [ "sphinx_rtd_theme", "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", "sphinx_sitemap", "zephyr.doxyrunner", "zephyr.doxybridge", "zephyr.doxytooltip", "zephyr.gh_utils", "zephyr.manifest_projects_table", "notfound.extension", "sphinx_copybutton", "sphinx_togglebutton", "zephyr.external_content", "zephyr.domain", "zephyr.api_overview", ] # Only use image conversion when it is really needed, e.g. LaTeX build. # Ensure "sphinxcontrib.rsvgconverter" is added before "sphinx.ext.imgconverter" # as it's better at converting SVG with extended features (like the ones from # draw.io) to PDF format). if tags.has("convertimages"): # pylint: disable=undefined-variable extensions.append("sphinxcontrib.rsvgconverter") extensions.append("sphinx.ext.imgconverter") 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"), ] SDK_URL_BASE="https://github.com/zephyrproject-rtos/sdk-ng/releases/download" rst_epilog = f""" .. include:: /substitutions.txt .. |sdk-version-literal| replace:: ``{sdk_version}`` .. |sdk-version-trim| unicode:: {sdk_version} :trim: .. |sdk-version-ltrim| unicode:: {sdk_version} :ltrim: .. _Zephyr SDK bundle: https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v{sdk_version} .. |sdk-url-linux| replace:: `{SDK_URL_BASE}/v{sdk_version}/zephyr-sdk-{sdk_version}_linux-x86_64.tar.xz` .. |sdk-url-linux-sha| replace:: `{SDK_URL_BASE}/v{sdk_version}/sha256.sum` .. |sdk-url-macos| replace:: `{SDK_URL_BASE}/v{sdk_version}/zephyr-sdk-{sdk_version}_macos-x86_64.tar.xz` .. |sdk-url-macos-sha| replace:: `{SDK_URL_BASE}/v{sdk_version}/sha256.sum` .. |sdk-url-windows| replace:: `{SDK_URL_BASE}/v{sdk_version}/zephyr-sdk-{sdk_version}_windows-x86_64.7z` """ # -- Options for HTML output ---------------------------------------------- html_theme = "sphinx_rtd_theme" html_theme_options = { "logo_only": True, "prev_next_buttons_location": None, "navigation_depth": 5, } 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") html_additional_pages = { "gsearch": "gsearch.html" } 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.7.0 (LTS)", "/3.7.0/"), ("3.6.0", "/3.6.0/"), ("2.7.6 (LTS)", "/2.7.6/"), ), "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", }, # Set google_searchengine_id to your Search Engine ID to replace built-in search # engine with Google's Programmable Search Engine. # See https://programmablesearchengine.google.com/ for details. "google_searchengine_id": "746031aa0d56d4912", } # -- 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 zephyr.doxybridge plugin --------------------------------- doxybridge_dir = doxyrunner_outdir # -- Options for html_redirect plugin ------------------------------------- html_redirect_pages = redirects.REDIRECTS # -- Options for zephyr.link-roles ---------------------------------------- link_roles_manifest_project = "zephyr" link_roles_manifest_project_broken_links_ignore_globs = [ "releases/release-notes-[123].*.rst", ] 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"), (ZEPHYR_BASE, "tests/**/*.pts"), ] external_content_keep = [ "reference/kconfig/*", "develop/manifest/index.rst", "build/dts/api/bindings.rst", "build/dts/api/bindings/**/*", "build/dts/api/compatibles/**/*", ] # -- Options for zephyr.domain -------------------------------------------- zephyr_breathe_insert_related_samples = True # -- 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 # -- Options for sphinx-sitemap ---------------------------------------- sitemap_url_scheme = "{link}" # -- 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 # -- Options for zephyr.api_overview -------------------------------------- api_overview_doxygen_base_url = "../../doxygen/html" def setup(app): # theme customizations app.add_css_file("css/custom.css") app.add_js_file("js/custom.js")