0.6.0

Release 0.6.0

New Features

• Stardoc no longer escapes HTML tags in documentation. Feel free to use HTML formatting in your docs! We now also have much-improved rendering for fenced code blocks in attribute docs, and render attribute default values using Markdown instead of HTML markup. (#161, #167)

• Stardoc now dedents and trims all doc strings - not only in macros (#170). This means you can have

  my_rule = rule(
      doc = """
      This is my rule.
  
      Here is more info about it.
  
      ...
      """,
      ...
  )

  and Stardoc will dedent and trim the doc to

  This is my rule.
  
  Here is more info about it.
  
  ...
  

• When using Bazel 7 or newer (or current Bazel HEAD), Stardoc will by default use the native starlark_doc_extract rule internally (#166).

  This means, in particular:

  • correct default values for rule attributes in all cases
  • documentation for module extensions
  • more complete documentation for repository rules
  • by default (this can be turned off via render_main_repo_name = False), we will render labels in your main repo with a repo component: your main module name (when using bzlmod) or WORKSPACE name (#168).

  You may temporarily disable the new extractor by calling Stardoc with use_starlark_doc_extract = False. However, after Bazel 7 is released, we plan to remove this argument and always use the new extractor.

Incompatible Changes

• The Markdown renderer now uses Google EscapeVelocity instead of Apache Velocity for templating. The templating engines are almost compatible, with the exception of escapes in string literals: if in your template you had a string literal with a character escape, you would need to expand it.

  For example, instead of

  ${funcInfo.docString.replaceAll("\n", " ")}

  you would need

  ${funcInfo.docString.replaceAll("
  ", " ")}

• When using the native starlark_doc_extract extractor, Stardoc requires two additional templates: repository_rule_template and
  module_extension_template. If you are using custom templates, you will probably want to define these, following the examples in
  stardoc/templates/markdown_tables.

• When using the native starlark_doc_extract extractor, Stardoc cannot document generated .bzl files any more - because Bazel cannot load() generated .bzl files.

Other Notable Changes

• The Markdown renderer's source now lives in the Stardoc repo; we build the renderer from source instead of using a bundled jar. Unfortunately, if you are not using bzlmod, this requires a rather complicated WORKSPACE setup; see below.

Contributors

Alexandre Rostovtsev, Fabian Meumertzheim

WORKSPACE setup

To use Stardoc, add the following to your WORKSPACE file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "io_bazel_stardoc",
    sha256 = "4441a965c97f8364c8eb901f951ca9a15c6e2c29ee0f10b56bf8b563463752ea",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.6.0/stardoc-0.6.0.tar.gz",
        "https://github.com/bazelbuild/stardoc/releases/download/0.6.0/stardoc-0.6.0.tar.gz",
    ],
)

load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")

stardoc_repositories()

load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")

rules_jvm_external_deps()

load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")

rules_jvm_external_setup()

load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")

stardoc_external_deps()

load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")

stardoc_pinned_maven_install()

The sequence of function calls and load statements after the io_bazel_stardoc repository definition ensures that this repository's dependencies are loaded (each function call defines additional repositories for Stardoc's dependencies, which are then used by subsequent load statements).

MODULE.bazel setup

bazel_dep(name = "stardoc", version = "0.6.0")

For compatibility with WORKSPACE setup (see above), add repo_name = "io_bazel_stardoc" to the bazel_dep call.

Using the rules

See the source.