envoy.docs.sphinx-runner

Sphinx docs builder used in Envoy proxy’s CI

Overview

envoy.docs.sphinx_runner wraps sphinx-build to orchestrate the Envoy proxy documentation build. It implements the aio.run.runner.Runner lifecycle: validate arguments, check the environment, write a build-config file, invoke Sphinx, and save the output. Sphinx warnings are treated as errors (-W --keep-going); when the build fails the tail of the captured warnings file is attached to the exception message to make failures self-diagnosing. Output is staged to a sibling path first and atomically swapped into place, so a failed build never destroys an existing output tree or tarball.

Installation

pip install envoy.docs.sphinx_runner

The package registers the console-script entry point envoy.docs.sphinx_runner (see [options.entry_points] in setup.cfg).

Usage

envoy.docs.sphinx_runner [options] RST_TAR OUTPUT_PATH

Positional arguments

RST_TAR: Path to a tarball containing the RST sources to render. The archive is extracted to a temporary build directory before Sphinx is invoked.
OUTPUT_PATH: Destination for the generated docs. When the path looks tar-like (.tar, .tar.gz, .tar.xz, .tar.bz2), the output is packed as a tarball; otherwise it is written as a directory.

Options

--build_sha SHA: Git SHA for the build; falls back to "UNKNOWN" when not supplied.
--build_target TARGET: Sphinx builder name (default: html). Supports any Sphinx builder, e.g. dirhtml, singlehtml, latex.
--docs_tag TAG: Explicit docs tag. When omitted, the tag is derived from the VERSION file: non-dev versions produce v<version>; dev versions produce an empty tag (pre-release build).
-j JOBS, --jobs JOBS: Sphinx parallel-build job count (default: auto).
--version_file PATH: Path to a VERSION file containing the semver string.
--version VERSION: Supply the version inline instead of reading --version_file.
--validator_path PATH: Path to a protobuf-validator binary. Presence implies --validate_fragments.
--descriptor_path PATH: Path to the protobuf file descriptor used for fragment validation.
--validate_fragments: Enable validation of validated-code-block RST directives.
--overwrite: Replace an existing OUTPUT_PATH. Without this flag the runner raises SphinxEnvError if the destination already exists.

Example

envoy.docs.sphinx_runner         --build_sha=abcdef1234         --version_file=./VERSION         --validator_path=./bin/validator         --descriptor_path=./api.pb         --validate_fragments         --overwrite         rst.tar.gz docs.tar.gz

Build configuration (ENVOY_DOCS_BUILD_CONFIG)

Before invoking Sphinx the runner writes a YAML configuration file to a temporary path and exports that path via the ENVOY_DOCS_BUILD_CONFIG environment variable. The consumer’s conf.py reads this file to inject Sphinx settings.

Keys always present:

version_string — full version identifier (e.g. tag-v1.30.0 or 1.30.0-abcdef).
release_level — "tagged" for versioned releases, "pre-release" otherwise.
blob_sha — the docs tag when present; otherwise the build SHA.
version_number — bare semver string read from the VERSION file.
docker_image_tag_name — Docker image tag derived from the semver (e.g. v1.29-latest).
intersphinx_mapping — cross-reference mapping built from versions.yaml in the RST tree.

Keys present only when fragment validation is enabled:

validator_path — path to the validator binary.
descriptor_path — path to the protobuf descriptor.

Key present only when fragment validation is disabled:

skip_validation — set to "true"; read by the validated-code-block extension to bypass proto checks.

Bundled Sphinx extensions

The package ships three Sphinx extensions under envoy/docs/sphinx_runner/ext/.

envoy.docs.sphinx_runner.ext.validating_code_block

Registers the validated-code-block RST directive, which extends the standard code-block directive to validate YAML snippets against a protobuf type. The required option :type-name: identifies the full Envoy API type. Descriptor path and skip-validation settings are read from ENVOY_DOCS_BUILD_CONFIG. An ExtensionError is raised on validation failure.

envoy.docs.sphinx_runner.ext.httpdomain

Wraps sphinxcontrib.httpdomain with a merge_domaindata override that suppresses spurious duplicate-method warnings produced during multi-core Sphinx builds.

envoy.docs.sphinx_runner.ext.powershell_lexer

Registers a PowerShell Pygments lexer so that .. code-block:: powershell blocks are syntax-highlighted correctly.

Enabling the extensions in conf.py

extensions = [
    "envoy.docs.sphinx_runner.ext.validating_code_block",
    "envoy.docs.sphinx_runner.ext.httpdomain",
    "envoy.docs.sphinx_runner.ext.powershell_lexer",
    # ... your other extensions
]

Error model

Two exception types are defined in envoy.docs.sphinx_runner.exceptions:

SphinxEnvError: Raised for pre-flight failures: git tag / VERSION mismatch, missing version-history file, or output path exists without --overwrite.
SphinxBuildError: Raised when Sphinx exits with a non-zero code. The message includes the exit code and, when available, the tail of the captured warnings file so failures are diagnosable without inspecting the full build log.

Development

Source and issues: https://github.com/envoyproxy/toolshed/tree/main/py/envoy.docs.sphinx_runner

Metadata

Release files for envoy.docs.sphinx-runner 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for envoy.docs.sphinx-runner 0.3.2
File	Size	Uploaded
envoy_docs_sphinx_runner-0.3.2.tar.gz	14.1 kB	May 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for envoy.docs.sphinx-runner 0.3.2
File	Interpreter	ABI	Platform	Reset
envoy_docs_sphinx_runner-0.3.2-py3-none-any.whl 12.8 kB May 15, 2026	Python 3	none	any	Details

Total release size: 26.9 kB

Release files / envoy_docs_sphinx_runner-0.3.2.tar.gz

Download URL	envoy_docs_sphinx_runner-0.3.2.tar.gz
Size	14.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`76ca59da2237b6aabc453ed067808aa7d603913e1de0ad8b2db3dddee99190be`
BLAKE2b-256 checksum How to use checksums	`3f0447dbdfecdb676d3cd7633e2de01f096705d932a8f2a33ae0592857f398a6`
Upload date	May 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Release files / envoy_docs_sphinx_runner-0.3.2-py3-none-any.whl

Download URL	envoy_docs_sphinx_runner-0.3.2-py3-none-any.whl
Size	12.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`fb66b380809bf910e45c904477510c0ccb2c808f65ff7a8794d9c65ab3d3bbae`
BLAKE2b-256 checksum How to use checksums	`ea9bf2b88220e0aa05d15a9853ee1d9052a1973995d9b64d9e62ddcf37255aa4`
Upload date	May 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`