Experiment with Buf and Starlark Docgen

The post explores the author's experimentation with documenting API docs for Bazel rules using the Starlark language, highlighting frustrations with the traditional tool Stardoc due to its reliance on outdated dependencies and cumbersome installation processes. The author discusses the challenges faced with Stardoc, such as its requirement for building Go code, dependency on a C++ compiler, and its complex integration with Maven. With the release of Bazel 7, a new approach using the built-in starlark_doc_extract rule is explored, which allows for extracting documentation without the need for Stardoc, and leverages the Buf Schema Registry to simplify parsing protocol buffers. The author demonstrates converting extracted docstrings into readable Markdown using Handlebars, a lightweight template engine, and also outlines how this process can be integrated into Bazel's BUILD files for ease of use. This experimentation serves as a potential alternative to Stardoc, providing insights into modernizing the documentation workflow for Bazel rules while also offering a link to the working code at the end for further exploration.