The sphinx_bzl Python package is a Sphinx plugin that defines a custom domain (“bzl”) in the Sphinx system. This provides first-class integration with Sphinx and allows code comments to provide rich information and allows manually writing docs for objects that aren't directly representable in bzl source code. For example, the fields of a provider can use :type: to indicate the type of a field, or manually written docs can use the {bzl:target} directive to document a well known target.
To enable the plugin in Sphinx, depend on @rules_python//sphinxdocs/src/sphinx_bzl and enable it in conf.py:
extensions = [
"sphinx_bzl.bzl",
]
To aid understanding how to write docs, lets define a few common terms:
{bzl:obj}`ref` . Roles mark inline text as needing special processing. There's generally two types of processing: creating cross references, or role-specific custom rendering. For example {bzl:obj} will create a cross references, while {bzl:default-value} indicates the default value of an argument.::: and allows defining an entire object and its parts. For example, to describe a function and its arguments, the :::{bzl:function} directive is used.:type: within a directive. Directive options are how directives are told the meaning of certain values, such as the type of a provider field. Depending on the object being documented, a directive option may be used instead of special role to indicate semantic values.Most often, you‘ll be using roles to refer other objects or indicate special values in doc strings. For directives, you’re likely to only use them when manually writing docs to document flags, targets, or other objects that sphinx_stardoc generates for you.
By default, Sphinx uses ReStructured Text (RST) syntax for its documents. Unfortunately, RST syntax is very different than the popular Markdown syntax. To bridge the gap, MyST translates Markdown-style syntax into the RST equivalents. This allows easily using Markdown in bzl files.
While MyST isn't required for the core sphinx_bzl plugin to work, this document uses MyST syntax because sphinx_stardoc bzl doc gen rule requires MyST.
Several roles or fields accept type expressions. Type expressions use Python-style annotation syntax to describe data types. For example None | list[str] describes a type of “None or a list of strings”. Each component of the expression is parsed and cross reference to its associated type definition.
In brief, to reference bzl objects, use the bzl:obj role and use the Bazel label string you would use to refer to the object in Bazel (using % to denote names within a file). For example, to unambiguously refer to py_binary:
{bzl:obj}`@rules_python//python:py_binary.bzl%py_binary`
The above is pretty long, so shorter names are also supported, and sphinx_bzl will try to find something that matches. Additionally, in .bzl code, the bzl: prefix is set as the default. The above can then be shortened to:
{obj}`py_binary`
The text that is displayed by be customized by putting the reference string in chevrons (<>):
{obj}`the binary rule <py_binary>`
Finally, specific types of objects (rules, functions, providers, etc) can be specified to help disambiguate short names:
{function}`py_binary` # Refers to the wrapping macro
{rule}`py_binary` # Refers to the underlying rule
Those are the basics of cross referencing. Sphinx has several additional syntaxes for finding and referencing objects; see the MyST docs for supported syntaxes
A cross reference role is the obj portion of {bzl:obj}. It affects what is searched and matched. Supported cross reference roles are:
{bzl:arg}: Refer to a function argument.{bzl:attr}: Refer to a rule attribute.{bzl:obj}: Refer to any type of Bazel object{bzl:rule}: Refer to a rule.{bzl:target}: Refer to a target.{bzl:type}: Refer to a type or type expression; can also be used in argument documentation.There are several special roles that can be used to annotate parts of objects, such as the type of arguments or their default values.
Indicate the default value for a function argument or rule attribute. Use it in the Args doc of a function or the doc text of an attribute.
def func(arg=1):
"""Do stuff
Args:
foo: {default-value}`1` the arg
my_rule = rule(attrs = {
"foo": attr.string(doc="{default-value}`bar`)
})
Indicates the return type for a function. Use it in the Returns doc of a function.
def func():
"""Do stuff
Returns:
{return-type}`int`
"""
return 1
Indicates the type of an argument for a function. Use it in the Args doc of a function.
def func(arg):
"""Do stuff
Args:
arg: {type}`int`
"""
print(arg + 1)
Most directives are automatically generated by sphinx_stardoc. Here, we only document ones that must be manually written.
To write a directive, a line starts with 3 to 6 colons (:), followed by the directive name in braces ({}), and eventually ended by the same number of colons on their own line. For example:
:::{bzl:target} //my:target
Doc about target
:::
This directive indicates the Bazel file that objects defined in the current documentation file are in. This is required for any page that defines Bazel objects.
Documents a target. It takes no directive options
:::{bzl:target} //foo:target
My docs
:::
Documents a flag. It has the same format as bzl:target