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
    ],
)

  • name (string, default: "docs") Name of the main documentation target. When left at its default, all generated targets keep their historical, unprefixed names (needs_json, sourcelinks_json, docs_check, ide_support, etc.) for backward compatibility. For any other name, every generated target is prefixed with it, e.g. name = "foo" yields foo, foo_check, foo_needs_json, foo_sourcelinks_json, foo_ide_support, and so on.

    Use a custom name when you need to call docs() more than once in the same BUILD file (e.g. to build two independent documentation sets); each call must then use a distinct name.

    docs(
    name = "foo",
    source_dir = "docs_foo",
)

    If you use a custom name and also rely on non-Bazel execution (e.g. Esbonio/IDE support via ide_support), set docs_target_name = "foo" in that source_dir’s conf.py to match, so the tooling can resolve the correctly-prefixed runfiles and Bazel targets outside of a bazel run invocation.

  • 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 modules.

    If you don’t provide the necessary Sphinx packages, this function adds its own (but checks for conflicts).

  • scan_code (list of bazel labels) Source code targets to scan for traceability tags (req-Id: annotations). Used to generate the source-code-link JSON that maps tags back to source files.

  • metamodel (bazel label, optional) Path to a custom metamodel.yaml file. When set, the score_metamodel extension loads this file instead of the default metamodel. The label is automatically added to the data and tools of every generated target so the file is available in the Bazel sandbox at build time.

    Example:

    docs(
    source_dir = "docs",
    metamodel = "//:my_metamodel.yaml",
)

    The custom metamodel.yaml must follow the same schema as the default one (see score_metamodel). You may use @score_docs_as_code//src/extensions/score_metamodel:metamodel_yaml for extension processing. When metamodel is omitted the default metamodel is used unchanged.

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.

  • If you depend on another module’s docs() output via data, and that module used a custom name, reference its prefixed target (e.g. @other_repo//:foo_needs_json) instead of the default needs_json.