Public API for docs helpers

Macros and Functions

stardoc_with_diff_test

Creates a stardoc target coupled with a diff_test for a given bzl_library.

This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.

Example usage (generated)

load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test")

stardoc_with_diff_test(
    # the label of the `bzl_library` target to generate documentation for
    bzl_library_target = None,
    # the label of the output MD file
    out_label = None,
)

bzl_library_target

the label of the bzl_library target to generate documentation for

out_label

the label of the output MD file

aspect_template

the label or path to the Velocity aspect template to use with stardoc

func_template

the label or path to the Velocity function/macro template to use with stardoc

header_template

the label or path to the Velocity header template to use with stardoc

provider_template

the label or path to the Velocity provider template to use with stardoc

rule_template

the label or path to the Velocity rule template to use with stardoc


update_docs

Creates a sh_binary target which copies over generated doc files to the local source tree.

This is to be used in tandem with stardoc_with_diff_test() to produce a convenient workflow for generating, testing, and updating all doc files as follows:

bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update

eg.

bazel build //docs/... && bazel test //docs/... && bazel run //docs:update

Example usage (generated)

load("@aspect_bazel_lib//lib:docs.bzl", "update_docs")

update_docs(
)

name

the name of the sh_binary target

docs_folder

the name of the folder containing the doc files in the local source tree