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 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). 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.