zdocs_conf

The shared Sphinx configuration every document’s conf.py shim calls into. Source: sphinx/zdocs_conf.py.

Shared Sphinx configuration for zdocs documents.

Each document’s conf.py is a thin shim that calls configure(), passing its own directory. This module is named zdocs_conf to not conflict with a docset wide conf_common` the user might have on the path as well.

Environment contract (all set by add_sphinx_target):

ZDOCS_CONF_DIR: Where this file lives. zdocs is a separate repository, checked out wherever the Zephyr module system put it, so no relative path from a consumer’s tree can reach it. (A consumer’s conf.py is read from its authored directory, so relative paths to the consumer’s own files work fine.)
ZDOCS_DOC_ID: The document’s registry key (its folder name).
ZDOCS_PROJECT_BASE: The consuming repository’s root — the git repo whose tags date the document.
ZDOCS_REGISTRY: Optional path to documents.yaml. Empty means a standalone document with no cross-references, which is a supported configuration, not a degraded one.
ZDOCS_DOC_BUILD_DIR, ZDOCS_DOC_DEPLOY_DIR, ZDOCS_DOC_BASE_URL: Build tree, deploy tree, and the URL the deploy tree is served under.

zdocs_conf.configure(namespace, doc_dir, project=None, author=None, copyright_holder=None, html_logo=None, extensions=None, static_path=None, css_files=None, templates_path=None, needs_config=None)[source]

Populate a document’s conf.py globals with the shared configuration.

doc_dir is the document’s own directory. project, author and copyright_holder are the consumer’s identity.

extensions is appended to the engine’s list rather than replacing it, so a consumer can add its own without having to restate the two-stage build’s requirements (and without being able to drop them by accident).