This document covers a number of advanced topics pertaining to using Stardoc.
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.
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.
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:
- Create a new custom output template to describe how this type of object should be rendered.
- In your
stardoc()target, set the matching
_templateattribute 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", )
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.
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
.proto file itself is provided (this prevents a transitive dependency on
proto rules to support only a very-advanced usecase). We recommend using rules
your own proto target using this source file, and adding it as a dependency of
your renderer binary.
To configure stardoc to output raw proto instead of markdown, use the
attribute of the stardoc rule. Specify
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 = ["@io_bazel_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)", )