//sphinxdocs:sphinx_stardoc.bzl

Rules to generate Sphinx-compatible documentation for bzl files.

sphinx_stardoc(name, src, deps=[], public_load_path=None, prefix=None, strip_prefix=None, create_test=True, output=None, **kwargs)

Generate Sphinx-friendly Markdown for a single bzl file.

Args:

• name – (Name)

  name for the target.

• src – (label)

  The bzl file to process, or a bzl_library target with one source file of the bzl file to process.

• deps – (list[label]) (default [])

  Targets that provide files loaded by src

• public_load_path – (str | None) (default None)

  override the file name that is reported as the file being.

• prefix – (str | None) (default None)

  prefix to add to the output file path

• strip_prefix – (str | None) (default None)

  Prefix to remove from the input file path. If not specified, then native.package_name is used.

• create_test – (bool) (default True)

  True if a test should be defined to verify the docs are buildable, False if not.

• output – (str | None) (default None)

  Optional explicit output file to use. If not set, the output name will be derived from src.

• kwargs – (dict)

  common args passed onto rules.

sphinx_stardocs(name, srcs=[], deps=[], docs={}, prefix=None, strip_prefix=None, **kwargs)

Generate Sphinx-friendly Markdown docs using Stardoc for bzl libraries.

A build_test for the docs is also generated to ensure Stardoc is able to process the files.

NOTE: This generates MyST-flavored Markdown.

Args:

• name – (Name)

  , the name of the resulting file group with the generated docs.

• srcs – (list[label]) (default [])

  Each source is either the bzl file to process or a bzl_library target with one source file of the bzl file to process.

• deps – (list[label]) (default [])

  Targets that provide files loaded by src

• docs – (dict[str, str | dict]) (default {})

  of the bzl files to generate documentation for. The output key is the path of the output filename, e.g., foo/bar.md. The source values can be either of:

  • A str label that points to a bzl_library target. The target name will replace _bzl with .bzl and use that as the input bzl file to generate docs for. The target itself provides the necessary dependencies.

  • A dict with keys input and dep. The input key is a string label to the bzl file to generate docs for. The dep key is a string label to a bzl_library providing the necessary dependencies.

• prefix – (str) (default None)

  Prefix to add to the output file path. It is prepended after strip_prefix is removed.

• strip_prefix – (str | None) (default None)

  Prefix to remove from the input file path; it is removed before prefix is prepended. If not specified, then native.package_name is used.

• kwargs – Additional kwargs to pass onto each sphinx_stardoc target