Build Rule Reference

Skylark rules

skylark_doc

skylark_doc(name, deps, srcs, format, link_ext, overview, overview_filename, site_root, skydoc, strip_prefix)

Generates Skylark rule documentation.

Documentation is generated in directories that follows the package structure of the input .bzl files. For example, suppose the set of input files are as follows:

foo/foo.bzl
foo/bar/bar.bzl

The archive generated by skylark_doc will contain the following generated docs:

foo/foo.html
foo/bar/bar.html

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; Default is []` List of other `skylark_library` targets that are required by the Skylark files listed in `srcs`.
`srcs`	`List of labels; Optional; Default is []` List of `.bzl` files that are processed to create this target.
`format`	`String; Optional; Default is 'markdown'` The type of output to generate. Possible values are `"markdown"` and `"html"`.
`link_ext`	`String; Optional; Default is ''` The file extension used for links in the generated documentation. By default, skydoc uses `.html`.
`overview`	`Boolean; Optional; Default is True` If set to `True`, then generate an overview page.
`overview_filename`	`String; Optional; Default is ''` The file name to use for the overview page. By default, the page is named `index.md` or `index.html` for Markdown and HTML output respectively.
`site_root`	`String; Optional; Default is ''` The site root to be prepended to all URLs in the generated documentation, such as links, style sheets, and images. This is useful if the generated documentation is served from a subdirectory on the web server. For example, if the skydoc site is to served from
`skydoc`	`Label; Optional; Default is //skydoc`
`strip_prefix`	`String; Optional; Default is ''` The directory prefix to strip from the generated output files. The directory prefix to strip must be common to all input files. Otherwise, skydoc will raise an error.

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".