android13/external/stardoc/docs/advanced_stardoc_usage.md

Contents

• Docstring Formatting
• Custom 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.

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.