FAQ
Skydoc

FAQ

Is Skydoc used to generate the documentation on Bazel.io?

Not for now. The Build Encyclopedia documents the set of native Bazel build rules written in Java, and the Skylark Library documents the built-in Skylark modules and functions. Because both of these sets of docs are generated from Bazel's Java source code, they are generated using a separate documentation generation tool.

We are planning to create a catalog of Skylark rule sets to make it easy to publish and discover Skylark rule sets and browse their documentation. See bazelbuild/bazel#1046 for more information.

Why do the docstrings for rules come after the rule definition?

Unlike in other languages, Python docstrings are special string literals rather than comments. Because Skylark is a subset of Python, we take the same approach for Skylark docstrings as well. Because rule declarations are basically global variables, we follow the same convention for variable docstrings used by Python documentation generation tools, such as epydoc.

Why skylark_library instead of skydoc_library?

The skylark_library rule is used to create logical sets of Skylark (.bzl) source files. Since Skylark is the name of the language, we decided to call this rule skylark_library and the rule for generating documentation from Skylark files skylark_doc. Potentially, we may reuse the skylark_library rules for other purposes, such as running lint tests on the .bzl files, etc. Also, this is consistent with the convention used for rules that we have for generating documentation for other programming languages, such as Rust and D (see the rust_library/rust_doc, d_library/d_docs rules respectively).

Note that if you only want to generate documentation for .bzl files in a single package (directory), you can simply use the skylark_doc rule and list all of the .bzl files in srcs. skylark_library is useful for generating documentation for a bunch of .bzl files spread across multiple different packages.