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
    ],
    bundles = [
        # dicts describing bundles to mount into this project
        # e.g. {"bundle": "@score_process//:docs_bundle", "mount_at": "process"}
    ],
    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. The items in data are added to the py_binaries and to the Sphinx tooling so they are available at build time.

    Note

    To pull in another module’s needs for cross-referencing, add its :needs_json target here.

  • bundles (list of placement dicts) Documentation bundles to overlay into this project’s documentation tree, each with its placement (mount_at). See Mount docs bundles for the full reference.

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

  • code_targets (list of Bazel labels) Implementation targets or filegroups to scan for traceability tags (req-Id: annotations). Implementation target srcs, hdrs, and textual_hdrs are collected through their deps recursively; filegroups expand to their files. Each documentation bundle produces one cache for its declared targets; Bazel reuses that cache while its inputs are unchanged. The generated JSON is supplied to live_preview just like a normal documentation build.

  • scan_code (list of Bazel labels, deprecated) Explicit source files or filegroups to scan. Use code_targets for implementation targets; it follows their dependencies automatically.

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

Bazel macro: docs_bundle#

docs_bundle (also from docs.bzl) declares a mountable documentation bundle: a chunk of RST/Markdown content that can be overlaid into a host documentation project. A bundle carries only content — it has no placement of its own. Where it appears is decided by whoever mounts it (a composing docs_bundle or the docs(bundles=[…]) call site).

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

docs_bundle(
    name = "docs_dir",
    source_dir = "docs",
    entry_doc = "index",
    bundles = [],
    visibility = ["//visibility:public"],
)

Signature: docs_bundle(name, source_dir = None, entry_doc = "index", bundles = [], scan_code = [], code_targets = [], visibility = None).

  • source_dir (string, optional) Directory holding the bundle’s own doc sources. It is globbed the same way as docs() (RST, Markdown, images, and the other doc file kinds). The source_dir itself is the mount root, so the files mount relative to it (so concept/index.rst with source_dir = "concept" becomes index.rst). The bundle exposes those files as a Bazel depset (via the DocsBundleInfo provider) and records the source_dir path; sphinx-mounts walks that original directory directly — no copy is made. Leave it unset for a pure aggregator that only composes bundles.

  • entry_doc (string, optional) Bundle-relative docname used as the canonical navigation entry. It defaults to index. Every mount attaches this entry to the parent index toctree by default; a placement’s attach_to may override that host document.

  • bundles (list of composition dicts, optional) Nested bundles to compose into this one, so a bundle can aggregate other bundles transitively. Each entry is a dict:

    • bundle — label of another docs_bundle target.

    • mount_at — the docname prefix at which the child bundle appears inside this bundle.

    • attach_to (optional) — a docname (relative to this bundle) whose toctree receives the child’s bundle-defined entry document. When omitted, the parent index document receives it.

    A child’s mount_at/attach_to prefix-stack with the placement this bundle later receives, so composition is fully transitive. The same underlying bundle resolving to two different final mount_at values is a hard build error. See Mount docs bundles for a worked example and Documentation bundles and mounts for the composition and transitivity semantics.

Note

A bundle is placement-free: its mount_at and attach_to are assigned by the mounter, while its entry_doc belongs to the bundle. This lets the same bundle be mounted at different locations by different consumers without changing its canonical entry page.

  • code_targets (list of Bazel labels, optional)

    Implementation targets or filegroups to scan for requirement tags. Implementation target srcs, hdrs, and textual_hdrs are collected recursively from their deps; filegroups expand to their files. The bundle owns one cached scan result; Bazel only regenerates it when its collected source inputs change.

  • scan_code (list of Bazel labels, deprecated)

    Explicit source files or filegroups to scan. Prefer code_targets for implementation targets.

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.