advanced_stardoc_usage.md

Contents

• Docstring Formatting
• Custom Output
• Proto Output

This document covers a number of advanced topics pertaining to using Stardoc.

Docstring Formatting

You may want to inline various kinds of formatting in the docstrings adjacent to your Starlark code. Use standard markdown formatting constructs instead of HTML tags.

For example:

def my_function(foo, bar):
  """Does some cool stuff.

  Oh, by the way, have you heard about [Stardoc](https://github.com/bazelbuild/stardoc)?

  Args:
    foo: You don't know what a **foo** is?
    bar: Two variables, `x` and `y`, walk in to a bar...
  """
  ...

Markdown formatting constructs are handled appropriately by Stardoc's default output format ("markdown_tables"), even as part of a table.

Custom Output

Stardoc's output format is customizable; while Stardoc's output is markdown by default, you may define a different output format for your documentation.

Customization is done at the level of "output templates". To customize the doc output for a particular type of Starlark definition (such as a "rule" or a "function"), you will need to:

1. Create a new custom output template to describe how this type of object should be rendered.
2. In your stardoc() target, set the matching _template attribute to point to your new output template.

For example, you might want to change the way rule documentation is generated. You might create a new output template file package/rule.vm and then define your stardoc target as follows:

stardoc(
    name = "my_docs",
    input = "my_rule.bzl",
    out = "my_rule_doc.md",
    rule_template = "//package:rule.vm",
)

The default values for the available templates may be found under templates/markdown_tables. See the Stardoc rule documentation for a comprehensive list of which '_template' attributes are available.

Writing a custom output template

Stardoc's output templates are defined using Velocity Template Language (VTL) with utilities and model objects available in the evaluation context.

The full comprehensive list of available utilities top-level objects is available in the source for MarkdownRenderer.

Information available for raw model objects (such rule information) is defined by Stardoc's underlying proto schema, vendored from the Bazel source tree.

This is a particularly advanced feature of Stardoc, so we would recommend using one of the existing canonical templates as a springboard to get started.

Proto Output

Stardoc provides the option to output documentation information in raw proto format. You may find this useful if you need output customization beyond Stardoc's current custom-output-template capabilities: you might prefer to build your own custom output renderer binary using the data that Stardoc acquires by fully evaluating a Starlark file. If your changes could be incorporated into Stardoc, please first consider contributing instead.

The proto schema may be found under stardoc/proto/stardoc_output.proto, vendored from the Bazel source tree.

To configure stardoc to output raw proto instead of markdown, use the format attribute of the stardoc rule. Specify "proto". An example:

stardoc(
    name = "docs_proto_output",
    out = "doc_output.raw",
    input = ":my_rule.bzl",
    deps = [":my_lib"],
    format = "proto",
)

# Define a proto_library target to incorporate the stardoc_output_proto
proto_library(
    name = "stardoc_output_proto",
    srcs = ["@stardoc//stardoc/proto:stardoc_output.proto"],
)

# You'll need to define your own rendering target. This might be a
# `genrule` or your own custom rule.
genrule(
    name = "docs_markdown_output",
    tools = ["my_renderer.sh"],
    srcs = ["doc_output.raw"],
    outs = ["doc_output.md"],
    cmd = "$(location :my_renderer.sh) $@ $(SRCS)",
)