Bazel macro: docs

The docs macro defined in docs.bzl is a convenience wrapper that creates a small set of Bazel targets to build, verify and preview the project’s Sphinx documentation, and to create a Python virtual environment for IDE support (Esbonio).

See commands for the targets/commands it creates.

The macro must be called from the repository root package.

Minimal example (root BUILD)

load("//:docs.bzl", "docs")

docs(
    source_dir = "docs",
    data = [
        # labels to any extra tools or data you want included
        # e.g. "//:needs_json" or other tool targets
    ],
    deps = [
        # additional bazel labels providing Python deps or other runfiles
    ],
)

• source_dir (string, default: "docs") Path (relative to repository root) to your Sphinx source directory. This is the folder that contains your conf.py and the top-level ReST/markdown sources.

• data (list of bazel labels) Extra runfiles / data targets that should be made available to the documentation targets. Typical entries are targets that generate or provide external data used by the docs, for example a :needs_json producer. The items in data are added to the py_binaries and to the Sphinx tooling so they are available at build time.

• deps (list of bazel labels) Additional Bazel dependencies to add to the Python binaries and the virtual environment target. Use this to add project-specific Python packages or extension libraries the docs build requires.

Edge cases

• If your Sphinx conf.py expects files generated by other Bazel targets, make sure those targets are included in the data list so they are available to the build driver.

• The experimental “combo” targets rewrite some data labels for combined builds; those are intended for advanced use and are optional for normal doc workflows.