`sphinx_bzl.bzl`

Sphinx extension for documenting Bazel/Starlark objects.

Module Contents

Classes

`_BzlAspect`	Documents an aspect.
`_BzlAttrInfo`
`_BzlCallable`	Abstract base class for objects that are callable.
`_BzlCsvField`	Field with a CSV list of values.
`_BzlCurrentFile`	Sets what bzl file following directives are defined in.
`_BzlDocField`	A non-repeated field with xref support.
`_BzlDomain`	Domain for Bazel/Starlark objects.
`_BzlField`	Documents a field of a provider.
`_BzlFlag`	Documents a flag
`_BzlFunction`	Documents a general purpose function.
`_BzlGroupedField`	A repeated fieled grouped as a list with xref support.
`_BzlIndex`	An index of a bzl file’s objects.
`_BzlModuleExtension`	Documents a module_extension.
`_BzlObject`	Base class for describing a Bazel/Starlark object.
`_BzlObjectId`	Identifies an object defined by a directive.
`_BzlProvider`	Documents a provider type.
`_BzlProviderField`
`_BzlRepositoryRule`	Documents a repository rule.
`_BzlRule`	Documents a rule.
`_BzlTagClass`	Documents a tag class for a module extension.
`_BzlTarget`	Documents an arbitrary target.
`_BzlTypedef`	Documents a typedef.
`_BzlXrefField`	Abstract base class to create cross references for fields.
`_DefaultValueRole`	Documents the default value for an arg or attribute.
`_ObjectEntry`	Metadata about a known object.
`_RequiredProvidersRole`	Documents the providers an attribute requires.
`_ReturnTypeRole`	Documents the return type for function.
`_TargetType`
`_TypeExprParser`	Parsers a string description of types to doc nodes.
`_TypeRole`	Documents a type (or type expression) with crossreferencing.

Functions

`_full_id_from_env`
`_full_id_from_parts`
`_index_node_tuple`
`_log_debug`
`_on_missing_reference`
`_parse_full_id`
`_position_iter`
`setup`

Data

`_GetObjectsTuple`
`_INDEX_SUBTYPE_ENTRY_WITH_SUB_ENTRIES`
`_INDEX_SUBTYPE_NORMAL`
`_INDEX_SUBTYPE_SUB_ENTRY`
`_LOG_PREFIX`
`_RoleRunResult`
`_T`
`_logger`

API

exception sphinx_bzl.bzl.InvalidValueError

Bases: Exception

Generic error for an invalid value instead of ValueError.

Sphinx treats regular ValueError to mean abort parsing the current chunk and continue on as best it can. Their error means a more fundamental problem that should cause a failure.

class sphinx_bzl.bzl._BzlAspect(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Documents an aspect.

Doc fields:

attr: Documents attributes of the aspect. Takes a single arg, the attribute name. Can be repeated. The special roles {default-value} and {arg-type} can be used to indicate the default value and type of attribute, respectively.
aspect-attributes: A CSV list of attribute names the aspect propagates along.

Example MyST usage

:::{bzl:repo-rule} myaspect

:attr foo: {default-value}`"foo"` {arg-type}`attr.string` foo doc string

:aspect-attributes: srcs, deps
:::

doc_field_types = None

class sphinx_bzl.bzl._BzlAttrInfo(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx.util.docutils.SphinxDirective

has_content = False

option_spec = None

optional_arguments = 0

required_arguments = 1

run()

class sphinx_bzl.bzl._BzlCallable(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Abstract base class for objects that are callable.

class sphinx_bzl.bzl._BzlCsvField(*args, body_domain: str = '', **kwargs)

Bases: sphinx_bzl.bzl._BzlXrefField

Field with a CSV list of values.

__init__(*args, body_domain: str = '', **kwargs)

make_field(types: dict[str, list[docutils.nodes.Node]], domain: str, item: tuple, env: sphinx.environment.BuildEnvironment = None, inliner: Union[docutils.parsers.rst.states.Inliner, None] = None, location: Union[docutils.nodes.Element, None] = None) → docutils.nodes.field

class sphinx_bzl.bzl._BzlCurrentFile(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx.util.docutils.SphinxDirective

Sets what bzl file following directives are defined in.

The directive’s argument is an absolute Bazel label, e.g. //foo:bar.bzl or @repo//foo:bar.bzl. The repository portion is optional; if specified, it will override the bzl_default_repository_name configuration setting.

Example MyST usage

:::{bzl:currentfile} //my:file.bzl
:::

final_argument_whitespace = False

has_content = False

required_arguments = 1

run() → list[docutils.nodes.Node]

class sphinx_bzl.bzl._BzlDocField(name: str, names: tuple[str, ...] = (), label: str = '', has_arg: bool = True, rolename: str = '', bodyrolename: str = '')

Bases: sphinx_bzl.bzl._BzlXrefField, sphinx.util.docfields.Field

A non-repeated field with xref support.

class sphinx_bzl.bzl._BzlDomain(env: sphinx.environment.BuildEnvironment)

Bases: sphinx.domains.Domain

Domain for Bazel/Starlark objects.

Directives

There are directives for defining Bazel objects and their functionality. See the respective directive classes for details.

Public Crossreferencing Roles

These are roles that can be used in docs to create cross references.

Objects are fully identified using dotted notation converted from the Bazel label and symbol name within a .bzl file. The @, / and : characters are converted to dots (with runs removed), and .bzl is removed from file names. The dotted path of a symbol in the bzl file is appended. For example, the paths.join function in @bazel_skylib//lib:paths.bzl would be identified as bazel_skylib.lib.paths.paths.join.

Shorter identifiers can be used. Within a project, the repo name portion can be omitted. Within a file, file-relative names can be used.

obj: Used to reference a single object without concern for its type. This roles searches all object types for a name that matches the given value. Example usage in MyST:
```
{bzl:obj}`repo.pkg.file.my_function`
```
type: Transforms a type expression into cross references for objects with object type “type”. For example, it parses int | list[str] into three links for each component part.

Public Typography Roles

These are roles used for special purposes to aid documentation.

default-value: The default value for an argument or attribute. Only valid to use within arg or attribute documentation. See _DefaultValueRole for details.
required-providers: The providers an attribute requires. Only valud to use within an attribute documentation. See _RequiredProvidersRole for details.
return-type: The type of value a function returns. Only valid within a function’s return doc field. See _ReturnTypeRole for details.

Object Types

These are the types of objects that this domain keeps in its index.

arg: An argument to a function or macro.
aspect: A Bazel aspect.
attribute: An input to a rule (regular, repository, aspect, or module extension).
method: A function bound to an instance of a struct acting as a type.
module-extension: A Bazel module_extension.
provider: A Bazel provider.
provider-field: A field of a provider.
repo-rule: A Bazel repository_rule.
rule: A regular Bazel rule.
tag-class: A Bazel tag_class of a module_extension.
target: A Bazel target.
type: A builtin Bazel type or user-defined structural type. User defined structual types are typically instances struct created using a function that acts as a constructor with implicit state bound using closures.

_find_entry_for_xref(fromdocname: str, object_type: str, target: str) → Union[sphinx_bzl.bzl._ObjectEntry, None]

add_object(entry: sphinx_bzl.bzl._ObjectEntry, alt_names=None) → None

directives = None

get_full_qualified_name(node: docutils.nodes.Element) → Union[str, None]

get_objects() → Iterable[sphinx_bzl.bzl._GetObjectsTuple]

indices = None

initial_data = None

label = 'Bzl'

merge_domaindata(docnames: list[str], otherdata: dict[str, Any]) → None

name = 'bzl'

object_types = None

resolve_any_xref(env: sphinx.environment.BuildEnvironment, fromdocname: str, builder: sphinx.builders.Builder, target: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element) → list[tuple[str, docutils.nodes.Element]]

resolve_xref(env: sphinx.environment.BuildEnvironment, fromdocname: str, builder: sphinx.builders.Builder, typ: str, target: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element) → Union[docutils.nodes.Element, None]

roles = None

class sphinx_bzl.bzl._BzlField(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Documents a field of a provider.

Fields can optionally have a type specified using the :type: option.

The type can be any type expression understood by the {bzl:type} role.

:::{bzl:provider-field} foo
:type: str
:::

_get_alt_names(object_entry)

_get_signature_object_type() → str

option_spec = 'copy(...)'

class sphinx_bzl.bzl._BzlFlag(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlTarget

Documents a flag

_TARGET_TYPE = None

_get_additional_index_types()

_get_signature_object_type() → str

class sphinx_bzl.bzl._BzlFunction(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlCallable

Documents a general purpose function.

Doc fields:

arg: Documents the arguments of the function. Takes a single arg, the arg name. Can be repeated. The special roles {default-value} and {arg-type} can be used to indicate the default value and type of attribute, respectively.
returns: Documents what the function returns. The special role {return-type} can be used to indicate the return type of the function.

Example MyST usage

:::{bzl:function} myfunc(a, b=None) -> bool

:arg a: {arg-type}`str` some arg doc
:arg b: {arg-type}`int | None` {default-value}`42` more arg doc
:returns: {return-type}`bool` doc about return value.
:::

_get_signature_object_type() → str

doc_field_types = None

class sphinx_bzl.bzl._BzlGroupedField(name: str, names: tuple[str, ...] = (), label: str = '', has_arg: bool = True, rolename: str = '', bodyrolename: str = '')

Bases: sphinx_bzl.bzl._BzlXrefField, sphinx.util.docfields.GroupedField

A repeated fieled grouped as a list with xref support.

class sphinx_bzl.bzl._BzlIndex(domain: sphinx.domains.Domain)

Bases: sphinx.domains.Index

An index of a bzl file’s objects.

NOTE: This generates the entries for the domain specific index (bzl-index.html), not the general index (genindex.html). To affect the general index, index nodes and directives must be used (grep for self.indexnode).

generate(docnames: Iterable[str] = None) → tuple[list[tuple[str, list[sphinx.domains.IndexEntry]]], bool]

localname = 'Bazel/Starlark Object Index'

name = 'index'

shortname = 'Bzl'

class sphinx_bzl.bzl._BzlModuleExtension(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Documents a module_extension.

Doc fields:

os-dependent: Documents if the module extension depends on the host architecture.
arch-dependent: Documents if the module extension depends on the host architecture.
environment-variables: a CSV list of environment variable names. They will be cross referenced with matching environment variables.

Tag classes are documented using the bzl:tag-class directives within this directive.

Example MyST usage:

::::{bzl:module-extension} myext

:os-dependent: True
:arch-dependent: False

:::{bzl:tag-class} mytag(myattr)

:attr myattr:
  {arg-type}`attr.string_list`
  doc for attribute
:::
::::

_get_signature_object_type() → str

doc_field_types = None

class sphinx_bzl.bzl._BzlObject(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx.directives.ObjectDescription[sphinx_bzl.bzl._BzlObjectId]

Base class for describing a Bazel/Starlark object.

This directive takes a single argument: a string name with optional function signature.

The name can be a dotted name, e.g. a.b.foo
The signature is in Python signature syntax, e.g. foo(a=x) -> R
The signature supports default values.
Arg type annotations are not supported; use {bzl:type} instead as part of arg/attr documentation.

Example signatures:

foo
foo(arg1, arg2)
foo(arg1, arg2=default) -> returntype

_get_additional_index_types()

_get_alt_names(object_entry)

_get_object_type_display_name() → str

_get_signature_object_type() → str

_object_hierarchy_parts(sig_node: sphinx.addnodes.desc_signature) → tuple[str, ...]

_signature_add_object_type(sig_node: sphinx.addnodes.desc_signature)

_toc_entry_name(sig_node: sphinx.addnodes.desc_signature) → str

add_target_and_index(obj_desc: sphinx_bzl.bzl._BzlObjectId, sig: str, sig_node: sphinx.addnodes.desc_signature) → None

after_content() → None

before_content() → None

handle_signature(sig_text: str, sig_node: sphinx.addnodes.desc_signature) → sphinx_bzl.bzl._BzlObjectId

option_spec = None

transform_content(content_node: sphinx.addnodes.desc_content) → None

class sphinx_bzl.bzl._BzlObjectId(*, repo: str, label: str, namespace: str = None, symbol: str = None)

Identifies an object defined by a directive.

This object is returned by handle_signature() and passed onto add_target_and_index(). It contains information to identify the object that is being described so that it can be indexed and tracked by the domain.

__init__(*, repo: str, label: str, namespace: str = None, symbol: str = None)

Creates an instance.

Args: repo: repository name, including leading “@”. bzl_file: label of file containing the object, e.g. //foo:bar.bzl namespace: dotted name of the namespace the symbol is within. symbol: dotted name, relative to namespace of the symbol.

__repr__()

classmethod from_env(env: sphinx.environment.BuildEnvironment, *, symbol: str = None, label: str = None) → sphinx_bzl.bzl._BzlObjectId

class sphinx_bzl.bzl._BzlProvider(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Documents a provider type.

Example MyST usage

::::{bzl:provider} MyInfo

Docs about MyInfo

:::{bzl:provider-field} some_field
:type: depset[str]
:::
::::

class sphinx_bzl.bzl._BzlProviderField(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): Bases: sphinx_bzl.bzl._BzlField

class sphinx_bzl.bzl._BzlRepositoryRule(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlCallable

Documents a repository rule.

Doc fields:

attr: Documents attributes of the rule. Takes a single arg, the attribute name. Can be repeated. The special roles {default-value} and {arg-type} can be used to indicate the default value and type of attribute, respectively.
environment-variables: a CSV list of environment variable names. They will be cross referenced with matching environment variables.

Example MyST usage

:::{bzl:repo-rule} myrule(foo)

:attr foo: {default-value}`"foo"` {arg-type}`attr.string` foo doc string

:environment-variables: FOO, BAR
:::

_get_signature_object_type() → str

doc_field_types = None

class sphinx_bzl.bzl._BzlRule(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlCallable

Documents a rule.

Doc fields:

attr: Documents attributes of the rule. Takes a single arg, the attribute name. Can be repeated. The special roles {default-value} and {arg-type} can be used to indicate the default value and type of attribute, respectively.
provides: A type expression of the provider types the rule provides. To indicate different groupings, use | and []. For example, FooInfo | [BarInfo, BazInfo] means it provides either FooInfo or both of BarInfo and BazInfo.

Example MyST usage

:::{bzl:repo-rule} myrule(foo)

:attr foo: {default-value}`"foo"` {arg-type}`attr.string` foo doc string

:provides: FooInfo | BarInfo
:::

doc_field_types = None

class sphinx_bzl.bzl._BzlTagClass(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlCallable

Documents a tag class for a module extension.

Doc fields:

attr: Documents attributes of the tag class. Takes a single arg, the attribute name. Can be repeated. The special roles {default-value} and {arg-type} can be used to indicate the default value and type of attribute, respectively.

Example MyST usage, note that this directive should be nested with a bzl:module-extension directive.

:::{bzl:tag-class} mytag(myattr)

:attr myattr:
  {arg-type}`attr.string_list`
  doc for attribute
:::

_get_alt_names(object_entry)

_get_signature_object_type() → str

doc_field_types = None

class sphinx_bzl.bzl._BzlTarget(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Documents an arbitrary target.

_TARGET_TYPE = None

_get_signature_object_type() → str

handle_signature(sig_text, sig_node)

class sphinx_bzl.bzl._BzlTypedef(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx_bzl.bzl._BzlObject

Documents a typedef.

A typedef describes objects with well known attributes.

::::{bzl:typedef} Square

:::{bzl:field} width
:type: int
:::

:::{bzl:function} new(size)
:::

:::{bzl:function} area()
:::
::::

class sphinx_bzl.bzl._BzlXrefField(name: str, names: tuple[str, ...] = (), label: str = '', has_arg: bool = True, rolename: str = '', bodyrolename: str = '')

Bases: sphinx.util.docfields.Field

Abstract base class to create cross references for fields.

_make_xrefs_for_arg_attr(rolename: str, domain: str, arg_name: str, innernode: type[sphinx.util.typing.TextlikeNode] = addnodes.literal_emphasis, contnode: Union[docutils.nodes.Node, None] = None, env: Union[sphinx.environment.BuildEnvironment, None] = None, inliner: Union[docutils.parsers.rst.states.Inliner, None] = None, location: Union[docutils.nodes.Element, None] = None) → list[docutils.nodes.Node]

make_xrefs(rolename: str, domain: str, target: str, innernode: type[sphinx.util.typing.TextlikeNode] = addnodes.literal_emphasis, contnode: Union[docutils.nodes.Node, None] = None, env: Union[sphinx.environment.BuildEnvironment, None] = None, inliner: Union[docutils.parsers.rst.states.Inliner, None] = None, location: Union[docutils.nodes.Element, None] = None) → list[docutils.nodes.Node]

class sphinx_bzl.bzl._DefaultValueRole

Bases: sphinx.util.docutils.SphinxRole

Documents the default value for an arg or attribute.

This is a special role used within :arg: and :attr: doc fields to indicate the default value. The rendering process looks for this role and reformats and moves its content for better display.

Styling can be customized by matching the .default_value class.

run() → sphinx_bzl.bzl._RoleRunResult

sphinx_bzl.bzl._GetObjectsTuple: typing_extensions.TypeAlias = None

sphinx_bzl.bzl._INDEX_SUBTYPE_ENTRY_WITH_SUB_ENTRIES = 1

sphinx_bzl.bzl._INDEX_SUBTYPE_NORMAL = 0

sphinx_bzl.bzl._INDEX_SUBTYPE_SUB_ENTRY = 2

sphinx_bzl.bzl._LOG_PREFIX = None

class sphinx_bzl.bzl._ObjectEntry(full_id: str, display_name: str, object_type: str, search_priority: int, index_entry: sphinx.domains.IndexEntry)

Metadata about a known object.

__init__(full_id: str, display_name: str, object_type: str, search_priority: int, index_entry: sphinx.domains.IndexEntry)

Creates an instance.

Args: full_id: The fully qualified id of the object. Should be globally unique, even between projects. display_name: What to display the object as in casual context. object_type: The type of object, typically one of the values known to the domain. search_priority: The search priority, see https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.Domain.get_objects for valid values. index_entry: Metadata about the object for the domain index.

__repr__()

to_get_objects_tuple() → sphinx_bzl.bzl._GetObjectsTuple

class sphinx_bzl.bzl._RequiredProvidersRole

Bases: sphinx_bzl.bzl._TypeRole

Documents the providers an attribute requires.

This is a special role used within :arg: or :attr: doc fields to indicate the types of providers that are required. The rendering process looks for this role and reformats its content for better display, but its position is left as-is; typically it would be its own paragraph near the end of the doc.

The syntax is a pipe (|) delimited list of types or groups of types, where groups are indicated using [...]. e.g, to express that FooInfo OR (both of BarInfo and BazInfo) are supported, write FooInfo | [BarInfo, BazInfo]

Example MyST Usage

:::{bzl:rule} foo(bar)

:attr bar: My attribute doc

  {required-providers}`CcInfo | [PyInfo, JavaInfo]`
:::

run() → sphinx_bzl.bzl._RoleRunResult

class sphinx_bzl.bzl._ReturnTypeRole

Bases: sphinx_bzl.bzl._TypeRole

Documents the return type for function.

This is a special role used within :returns: doc fields to indicate the return type of the function. The rendering process looks for this role and reformats and moves its content for better display.

Example MyST Usage

:::{bzl:function} foo()

:returns: {return-type}`list[str]`
:::

run() → sphinx_bzl.bzl._RoleRunResult

sphinx_bzl.bzl._RoleRunResult: typing_extensions.TypeAlias = None

sphinx_bzl.bzl._T = 'TypeVar(...)'

class sphinx_bzl.bzl._TargetType

Bases: enum.Enum

FLAG = 'flag'

TARGET = 'target'

class sphinx_bzl.bzl._TypeExprParser(make_xref: Callable[[str], docutils.nodes.Node])

Bases: ast.NodeVisitor

Parsers a string description of types to doc nodes.

__init__(make_xref: Callable[[str], docutils.nodes.Node])

_append(node: docutils.nodes.Node)

_append_and_push(node: docutils.nodes.Node)

generic_visit(node)

visit_Attribute(node: ast.Attribute)

visit_BinOp(node: ast.BinOp)

visit_Constant(node: ast.Constant)

visit_Expr(node: ast.Expr)

visit_List(node: ast.List)

visit_Name(node: ast.Name)

visit_Subscript(node: ast.Subscript)

visit_Tuple(node: ast.Tuple)

classmethod xrefs_from_type_expr(type_expr_str: str, make_xref: Callable[[str], docutils.nodes.Node]) → docutils.nodes.Node

class sphinx_bzl.bzl._TypeRole

Bases: sphinx.util.docutils.SphinxRole

Documents a type (or type expression) with crossreferencing.

This is an inline role used to create cross references to other types.

The content is interpreted as a reference to a type or an expression of types. The syntax uses Python-style sytax with | and [], e.g. foo.MyType | str | list[str] | dict[str, int]. Each symbolic name will be turned into a cross reference; see the domain’s documentation for how to reference objects.

Example MyST usage:

This function accepts {bzl:type}`str | list[str]` for usernames

__init__()

run() → sphinx_bzl.bzl._RoleRunResult

sphinx_bzl.bzl._full_id_from_env(env, object_ids=None)

sphinx_bzl.bzl._full_id_from_parts(repo, bzl_file, symbol_names=None)

sphinx_bzl.bzl._index_node_tuple(entry_type: str, entry_name: str, target: str, main: Union[str, None] = None, category_key: Union[str, None] = None) → tuple[str, str, str, Union[str, None], Union[str, None]]

sphinx_bzl.bzl._log_debug(message, *args)

sphinx_bzl.bzl._logger = 'getLogger(...)'

sphinx_bzl.bzl._on_missing_reference(app, env: sphinx.environment.BuildEnvironment, node, contnode)

sphinx_bzl.bzl._parse_full_id(full_id)

sphinx_bzl.bzl._position_iter(values: collections.abc.Collection[sphinx_bzl.bzl._T]) → tuple[bool, bool, sphinx_bzl.bzl._T]

sphinx_bzl.bzl.setup(app)

sphinx_bzl.bzl

Module Contents

Classes

Functions

Data

API

`sphinx_bzl.bzl`