rules_doc

rules_doc

Pitch

A turn-key solution for generating documentation, integrating nicely with starlark_doc_extract.

Motivation

Integrating stardoc and bazel_skylib_gazelle_plugin is not a great developer experience:

• Only adds (non-maintained) bzl_library targets
• Have to manually add stardoc targets
• stardoc HTML output is awful
• Have to maintain own Velocity templates
• Integrating handwritten Markdown/HTML is a pain as it requires standalone templating

It is all-around not good.

Gathering .bzl files

Currently, the load graph for .bzl files needs to be replicated with the Gazelle plugin to generate bzl_library targets.

This is a pain.

Ideally, Bazel would provide a general rule that gives the .bzl graph for a given file:

# Returns a `depset` of the provided file and the loaded `.bzl` files
# Bikeshedding welcome on the name of the target
bzl_load_graph(
    name = "bzl",
    src = "abc.bzl",
)

API

A macro that wraps bzl_load_graph and starlark_doc_extract

load("@rules_docs//docs/data:defs.bzl", "docs_data")
load("@rules_docs//docs/render:defs.bzl", "docs_render")

# Proposed Bazel native rule (above)
bzl_load_graph(
    name = "graph",
    src = "defs.bzl",
)

# Converts to unstable protobuffer
starlark_doc_extract(
    name = "extract",
    src = ":graph",
)

# Converts unstable protobuffer to stable data (JSON?)
# Creates `DocsDataInfo`
docs_data(
    name = "data",
    src = ":extract.binaryproto",
    deps = [":other"],             # Added into the `DocsDataInfo` `depset`
)

# Renders the data using a templating engine (Go templating?)
docs_render(
    name = "render",
    srcs = [
        ":data",            # Must have at least one `DocsDataInfo`
        "index.tmpl.html",  # Can use the provided data to render
    ],
    deps = [
        ":other-docs",      # Can list other rendered documentation targets to combine
    ],
)

The render rule will also be a runnable target that copies the rendered files into a directory for publishing:

$ bazel run -- :render --output public # build documentation and copy it to the `public` directory

Developer Experience

We would provide a turn-key set of templates and macros for engineers to use:

load("@rules_docs//docs/html:defs.bzl", "docs_html")

# Combines `bzl_load_graph`, `starlark_doc_extract`, `docs_data` and `docs_render`
# Uses `@rules_docs//docs/template/html` 
docs_html(
    name = "docs",
    srcs = ["abc.bzl", "def.bzl"],
)

Then to publish their documentation, bazel run -- :render --output public.