Build Rule Reference
Skydoc

Build Rule Reference

Skylark rules

skydoc_repositories

skydoc_repositories()

Adds the external repositories used by the skylark rules.

skylark_doc

skylark_doc(name, deps, srcs, format, skydoc)

Generates Skylark rule documentation.

Outputs

%{name}-skydoc.zip

A zip file containing the generated documentation.

Attributes

name

Name; Required

A unique name for this rule.

deps

List of labels; Optional

List of other skylark_library targets that are required by the Skylark files listed in srcs.

srcs

List of labels; Optional

List of .bzl files that are processed to create this target.

format

String; Optional

The type of output to generate. Possible values are "markdown" and "html".

skydoc

Label; Optional

Examples

Suppose you have a project containing Skylark rules you want to document:

[workspace]/
    WORKSPACE
    checkstyle/
        BUILD
        checkstyle.bzl

To generate documentation for the rules and macros in checkstyle.bzl, add the following target to rules/BUILD:

load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc")

skylark_doc(
    name = "checkstyle-docs",
    srcs = ["checkstyle.bzl"],
)

Running bazel build //checkstyle:checkstyle-docs will generate a zip file containing documentation for the public rules and macros in checkstyle.bzl.

By default, Skydoc will generate documentation in Markdown. To generate a set of HTML pages that is ready to be served, set format = "html".

skylark_library

skylark_library(name, deps, srcs)

Creates a logical collection of Skylark .bzl files.

Attributes

name

Name; Required

A unique name for this rule.

deps

List of labels; Optional

List of other skylark_library targets that are required by the Skylark files listed in srcs.

srcs

List of labels; Optional

List of .bzl files that are processed to create this target.

Examples

If you would like to generate documentation for multiple .bzl files in various packages in your workspace, you can use the skylark_library rule to create logical collections of Skylark sources and add a single skylark_doc target for building documentation for all of the rule sets.

Suppose your project has the following structure:

[workspace]/
    WORKSPACE
    BUILD
    checkstyle/
        BUILD
        checkstyle.bzl
    lua/
        BUILD
        lua.bzl
        luarocks.bzl

In this case, you can have skylark_library targets in checkstyle/BUILD and lua/BUILD:

checkstyle/BUILD:

load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_library")

skylark_library(
    name = "checkstyle-rules",
    srcs = ["checkstyle.bzl"],
)

lua/BUILD:

load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_library")

skylark_library(
    name = "lua-rules",
    srcs = [
        "lua.bzl",
        "luarocks.bzl",
    ],
)

To build documentation for all the above .bzl files at once:

BUILD:

load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc")

skylark_doc(
    name = "docs",
    deps = [
        "//checkstyle:checkstyle-rules",
        "//lua:lua-rules",
    ],
)

Running bazel build //:docs would build a single zip containing documentation for all the .bzl files contained in the two skylark_library targets.