Autobazel¶

Autobazel-directives allow the automatic documentation of Bazel workspaces, packages, targets, rules, marcos, implementations and rule attributes.

All showed examples are based on the same Bazel example workspace, which structure and content is explained at the end of this page: Example project structure.

autobazel-workspace ¶

Documents a whole Bazel workspace:

.. autobazel-workspace:: ./bazel_example

Result

hello_world_workspace (bazel_example)

My workspace description

# Some python code
print("awesome")

If the given path is relative, the sphinx configuration folder is taken as basedir (the one which contains your conf.py file)

autobazel-package ¶

Documents a single Bazel package:

.. autobazel-package:: //lib

Result

//lib: LIB package: provides awesome stuff.

Sphinx-Bazel links all packages internally to a defined workspace, so that it is able to calculate needed folder and file paths of the package. Please be sure you use autobazel-workspace, .. bazel:workspace:: or path to define the location of the workspace to use.

autobazel-target ¶

Documents a single Bazel target:

.. autobazel-target:: //main:hello-world.bzl

Result

//main:hello-world.bzl

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

Like in autobazel-package please make sure that a workspace got defined.

autobazel-target searches for docstrings in files with extension .bzl and use this as target-description. Other file-extension are not supported, as they normally do not follow the Python syntax.

autobazel-rule ¶

Documents a single Bazel rule:

.. autobazel-rule:: //main:hello-world.bzl:custom_build_rule

Result

//main:hello-world.bzl:custom_build_rule: Explanation of custom_build_rule. Taken from doc attribute of rule definition.

Like in autobazel-package please make sure that a workspace got defined.

autobazel-rule searches for docstrings in the doc-attribute of a rule defined in files with extension .bzl. This is then used as rule description.

autobazel-macro ¶

Documents a single Bazel macro:

.. autobazel-macro:: //main:hello-world.bzl:custom_macro

Result

//main:hello-world.bzl:custom_macro

Custom macro documentation example. Args:

Param format:	The format to write check report in.
Param srcs:	Source files to run the checks against.

Like in autobazel-package please make sure that a workspace got defined.

autobazel-macro uses the docstring of the function/macro as macro description.

autobazel-implementation ¶

Documents a Bazel implementation of a rule:

.. autobazel-implementation:: //main:hello-world.bzl:__impl_custom_build_rule

Result

//main:hello-world.bzl:__impl_custom_build_rule: Documentation of the custom_build_rule implementation.

Like in autobazel-package please make sure that a workspace got defined.

autobazel-implementation uses the docstring of the implementation as implementation description.

autobazel-attribute ¶

Documents a specific Bazel rule attribute:

.. autobazel-attribute:: //main:hello-world.bzl:custom_build_rule:package_script

Result

//main:hello-world.bzl:custom_build_rule:package_script: Python script for simple file packaging

autobazel-attribute searches for docstrings in the doc-attribute of an attribute.

Options ¶

Most options are supported by the above directives, as they are very common. However, some are not. So here is an overview about which autobazel directive supports what kind of options.

Used abbreviations: ws=workspace, pack=package, targ=target, impl=implementation, attr=attribute

Option/autobazel-…	ws	pack	targ	rule	macro	impl	attr
path	⛔	👍	👍	👍	👍	👍	👍
name	👍	⛔	⛔	⛔	⛔	⛔	⛔
packages	👍	👍	⛔	⛔	⛔	⛔	⛔
targets	👍	👍	⛔	⛔	⛔	⛔	⛔
rules	👍	👍	👍	⛔	⛔	⛔	⛔
macros	👍	👍	👍	⛔	⛔	⛔	⛔
implementations	👍	👍	👍	⛔	⛔	⛔	⛔
attributes	👍	👍	👍	👍	⛔	⛔	⛔
hide	👍	👍	👍	👍	👍	👍	👍
show_implementation	👍	👍	👍	👍	⛔	⛔	⛔
show_invocation	👍	👍	👍	👍	⛔	⛔	⛔
show_workspace	👍	👍	👍	👍	👍	👍	👍
show_workspace_path	👍	👍	👍	👍	👍	👍	👍
raw	👍	👍	👍	👍	👍	👍	👍
show_type	👍	👍	👍	👍	👍	👍	👍

path ¶

ws	pack	targ	rule	macro	impl.	attr
⛔	👍	👍	👍	👍	👍	👍

If :path: is set, Sphinx-Bazel checks this folder directly without the need of a valid or existing Bazel workspace.

The following example package path is created from path + autobazel_package argument:

.. autobazel-package:: //main
   :path: ./bazel_example/
   :show_workspace_path:

This will look for a BUILD file in ./bazel_examples/main.

Result

//main workspace path: /home/docs/checkouts/readthedocs.org/user_builds/sphinx-bazel/checkouts/latest/docs/source/./bazel_example/: MAIN package: does awesome things.

Usage

The normal way is to not use this option and use autobazel-workspace or bazel:workspace instead. These directives will create a workspace internally and all following directives like autobazel-target or bazel:rule: will use this workspace as reference automatically.

However, there may be use cases where a workspace does not exist (e.g. single .bzl. files in a git submodule). In this cases this option can help.

name ¶

ws	pack	targ	rule	macro	impl.	attr
👍	⛔	⛔	⛔	⛔	⛔	⛔

:name: can be used to define a specific name of a workspace.

Normally the name gets read from the WORKSPACE file. If no name is defined or there are reasons to document workspaces with similar names, use :name:

.. autobazel-workspace:: ./bazel_example/
   :name: my custom workspace name
   :show_workspace_path:
   :show_workspace:

Result

my custom workspace name (./bazel_example/)

My workspace description

# Some python code
print("awesome")

Note

This documentation uses the same workspace bazel_example several times on the same page. To avoid warnings like WARNING: Duplicate ID: "workspace-hello_world_workspace", we use :name: to import the same workspace multiple times under different names.

packages ¶

ws	pack	targ	rule	macro	impl.	attr
👍	⛔	⛔	⛔	⛔	⛔	⛔

If :packages: is set, all found Bazel packages inside workspace will be printed as well:

.. autobazel-workspace:: ./bazel_example
   :packages:

Result

ws_package_example (./bazel_example)

My workspace description

# Some python code
print("awesome")

//main: MAIN package: does awesome things.

//lib: LIB package: provides awesome stuff.

regular expression ¶

:packages: can also contain a regular expression which documents only packages, which match the given expression:

.. autobazel-workspace:: ./bazel_example
   :packages: .*lib.*

The above regular expression searches for all packages, which have lib in their name.

Result

ws_package_example2 (./bazel_example)

My workspace description

# Some python code
print("awesome")

//lib: LIB package: provides awesome stuff.

targets ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	⛔	⛔	⛔	⛔	⛔

If :targets: is set, all found Bazel targets inside found packages will be printed as well:

.. autobazel-package:: //main
   :path: ./bazel_example
   :targets:

Result

//main: MAIN package: does awesome things.

//main:hello-world.cc

//main:hello-world.bzl

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

//main:hello-greet.cc

//main:hello-greet.h

With the above given regular expression sphinx-bazel will only care about targets, which have .cc as file ending.

regular expression ¶

:targets: can also contain a regular expression which documents only targets, which match the given expression:

.. autobazel-package:: //main
   :path: ./bazel_example
   :targets: .*.cc

With the above given regular expression sphinx-bazel will only care about targets, which have .cc as file ending.

Result

//main: MAIN package: does awesome things.

//main:hello-world.cc

//main:hello-greet.cc

rules ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	⛔	⛔	⛔	⛔

If :rules: is set, all found rules inside targets with extension .bzl files will be printed

.. autobazel-target:: //main:hello-world.bzl
   :path: ./bazel_example
   :rules:

Result

//main:hello-world.bzl

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

//main:hello-world.bzl:custom_build_rule: Explanation of custom_build_rule. Taken from doc attribute of rule definition.

macros ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	⛔	⛔	⛔	⛔

If :macros: is set, all found macros inside targets with extension .bzl files will be printed

.. autobazel-target:: //main:hello-world.bzl
   :path: ./bazel_example
   :macros:

Is only used, if :packages: and :targets: are provided as well!

Result

//main:hello-world.bzl

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

//main:hello-world.bzl:custom_macro

Custom macro documentation example. Args:

Param format:	The format to write check report in.
Param srcs:	Source files to run the checks against.

implementations ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	⛔	⛔	⛔	⛔

If :implementations: is set, all found implementations inside targets with extension .bzl files will be printed

.. autobazel-target:: //main:hello-world.bzl
   :path: ./bazel_example
   :implementations:

Result

//main:hello-world.bzl

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

//main:hello-world.bzl:__impl_custom_build_rule: Documentation of the custom_build_rule implementation.

attributes ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	⛔	⛔	⛔

If :attributes: is set, all found attributes of a rule will be printed

.. autobazel-rule:: //main:hello-world.bzl:custom_build_rule
   :path: ./bazel_example
   :attributes:

Result

//main:hello-world.bzl:custom_build_rule: Explanation of custom_build_rule. Taken from doc attribute of rule definition.

//main:hello-world.bzl:custom_build_rule:targets: List of dependency rules which are building libraries

//main:hello-world.bzl:custom_build_rule:package_name: Test string

//main:hello-world.bzl:custom_build_rule:package_script: Python script for simple file packaging

hide ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	👍	👍	👍

If :hide: is set, information about the workspace itself will not be printed. But packages and co, if requested:

.. autobazel-workspace:: ./bazel_example
    :hide:
    :packages:

Result

//main: MAIN package: does awesome things.

//lib: LIB package: provides awesome stuff.

show_implementation ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	⛔	⛔	⛔

If show_implementation is given, the name of the implementation function of found rules gets printed:

.. autobazel-rule:: //main:hello-world.bzl:custom_build_rule
   :path: ./bazel_example
   :show_implementation:

Result

//main:hello-world.bzl:custom_build_rule implementation: __impl_custom_build_rule: Explanation of custom_build_rule. Taken from doc attribute of rule definition.

show_invocation ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	⛔	⛔	⛔

If show_invocation is given, a generated invocation string based on name an attribute names gets printed:

.. autobazel-rule:: //main:hello-world.bzl:custom_build_rule
   :path: ./bazel_example
   :show_invocation:

Result

//main:hello-world.bzl:custom_build_rule invocation: custom_build_rule(targets, package_name, package_script): Explanation of custom_build_rule. Taken from doc attribute of rule definition.

show_workspace ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	👍	👍	👍

If :show_workspace is given, the workspace name will get added:

.. autobazel-workspace:: ./bazel_example
   :show_workspace:
   :packages:

Result

ws_show_workspace_example (./bazel_example)

My workspace description

# Some python code
print("awesome")

//main workspace: ws_show_workspace_example: MAIN package: does awesome things.

//lib workspace: ws_show_workspace_example: LIB package: provides awesome stuff.

show_workspace_path ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	👍	👍	👍

If :workspace_path is given, the workspace path will get added packages and targets:

.. autobazel-attribute:: //main:hello-world.bzl:custom_build_rule:package_script
   :path: ./bazel_example
   :show_workspace_path:

Result

//main:hello-world.bzl:custom_build_rule:package_script workspace path: /home/docs/checkouts/readthedocs.org/user_builds/sphinx-bazel/checkouts/latest/docs/source/./bazel_example: Python script for simple file packaging

raw ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	👍	👍	👍

Deactivates the rendering of imported doc-string / doc-attributes. Instead the content will be shown in a code-block.

This may be needed, if a bazel element gets documented multiple times and its rst-based doc-string contains elements, which should only get rendered once. For instance a sphinx needs requirement, which must be unique.

.. autobazel-package:: //lib
   :raw:

Result

//lib

LIB package: provides **awesome** stuff.

show_type ¶

ws	pack	targ	rule	macro	impl.	attr
👍	👍	👍	👍	👍	👍	👍

Adds a prefix like package: to show the type.

If using HTML as builder, the prefix will have the css classes: bazel , type and one of the following types: workspace, package, rule, implementation, macro or attribute.

.. autobazel-package:: //main
   :targets:
   :rule:
   :show_type:

Result

package: //main: MAIN package: does awesome things.

target: //main:hello-world.cc

target: //main:hello-world.bzl

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

rule: //main:hello-world.bzl:custom_build_rule: Explanation of custom_build_rule. Taken from doc attribute of rule definition.

target: //main:hello-greet.cc

target: //main:hello-greet.h

Example project structure ¶

The following project structure was used for the above examples:

./bazel_example
├── lib
│   ├── BUILD
│   ├── hello-time.cc
│   └── hello-time.h
├── main
│   ├── BUILD
│   ├── hello-greet.cc
│   ├── hello-greet.h
│   ├── hello-world.bzl
│   └── hello-world.cc
└── WORKSPACE

This structure is coming from the original Bazel examples repository and was updated to provide more internal documentation (e.g. docstrings): https://github.com/bazelbuild/examples/

WORKSPACE content ¶

"""
**My workspace description**

.. code-block:: python

   # Some python code
   print("awesome")
"""

workspace(name = "hello_world_workspace")

lib/BUILD content ¶

"""
LIB package: provides **awesome** stuff.
"""

cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)

main/BUILD content ¶

"""
MAIN package: does **awesome** things.
"""

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)

main/hello-world.bzl content ¶

"""
An *example* .bzl file.

You will find here a rule, a macro and the implementation function for the rule.
"""


def custom_macro(name, format, srcs=[]):
    '''Custom macro documentation example.
    Args:

    :param format: The format to write check report in.
    :param srcs: Source files to run the checks against.

    '''
    pass


def __impl_custom_build_rule(ctx):
    """Documentation of the custom_build_rule implementation."""

    filesd = None
    return [DefaultInfo(files=filesd)]


custom_build_rule = rule(
    implementation = __impl_custom_build_rule,
    doc = """Explanation of **custom_build_rule**. Taken from `doc` attribute of rule definition.
""",
    attrs = {
        "targets": attr.label(
            mandatory=True,
            allow_files=True,
            doc="List of dependency rules which are building libraries"),
        "package_name": attr.string(
            mandatory=True,
            doc="Test string"),
        "package_script": attr.label(
            mandatory=False,
            default="//scripts:doc_gen_logger.py",
            allow_single_file=True,
            doc="Python script for simple file packaging"),
    }
)

Complete documentation ¶

The following documentation of the complete Bazel Workspace uses nearly every available option:

.. autobazel-workspace:: ./bazel_example
   :name: ws_full_example
   :packages:               // from here content options
   :targets:
   :rules:
   :macros:
   :implementations:
   :attributes:
   :show_workspace:         // from here layout options only
   :show_workspace_path:
   :show_implementation:
   :show_invocation:
   :show_type:

Result

workspace: ws_full_example (./bazel_example)

My workspace description

# Some python code
print("awesome")

package: //main workspace: ws_full_example workspace path: ./bazel_example: MAIN package: does awesome things.

target: //main:hello-world.cc workspace: ws_full_example workspace path: ./bazel_example

target: //main:hello-world.bzl workspace: ws_full_example workspace path: ./bazel_example

An example .bzl file.

You will find here a rule, a macro and the implementation function for the rule.

rule: //main:hello-world.bzl:custom_build_rule workspace: ws_full_example workspace path: ./bazel_example implementation: __impl_custom_build_rule invocation: custom_build_rule(targets, package_name, package_script): Explanation of custom_build_rule. Taken from doc attribute of rule definition.

attribute: //main:hello-world.bzl:custom_build_rule:targets workspace: ws_full_example workspace path: ./bazel_example: List of dependency rules which are building libraries

attribute: //main:hello-world.bzl:custom_build_rule:package_name workspace: ws_full_example workspace path: ./bazel_example: Test string

attribute: //main:hello-world.bzl:custom_build_rule:package_script workspace: ws_full_example workspace path: ./bazel_example: Python script for simple file packaging

macro: //main:hello-world.bzl:custom_macro workspace: ws_full_example workspace path: ./bazel_example

Custom macro documentation example. Args:

Param format:	The format to write check report in.
Param srcs:	Source files to run the checks against.

implementation: //main:hello-world.bzl:__impl_custom_build_rule workspace: ws_full_example workspace path: ./bazel_example: Documentation of the custom_build_rule implementation.

target: //main:hello-greet.cc workspace: ws_full_example workspace path: ./bazel_example

target: //main:hello-greet.h workspace: ws_full_example workspace path: ./bazel_example

package: //lib workspace: ws_full_example workspace path: ./bazel_example: LIB package: provides awesome stuff.

target: //lib:hello-time.cc workspace: ws_full_example workspace path: ./bazel_example

target: //lib:hello-time.h workspace: ws_full_example workspace path: ./bazel_example