Bazel DocGen (1/3): Make link expansion mechanism more powerful.
# Motivation
Linking from one part of the Blaze/Bazel (“Blazel”) documentation to another one is surprisingly difficult due to various distinctions (native code vs Starlark, Blaze vs Bazel, generated vs narrative documentation). As a result, we’ve implemented various hacks or simply tolerated broken links.
# Contributions
This CL addresses the problems by doubling down on dynamic link expansion:
- RuleLinkExpander can now be used to link to any file in the build encyclopedia (“BE”): While the `${link foo}` syntax was originally intended for linking to rule families, a previous version already contained a hack to link to some static documentation files. This CL super-charges RuleLinkExpander by allowing it to link to *any* BE file, based on an explicit link mapping that has to be defined in a JSON configuration file. As a result, it’s clearly visible which files diverge between Blaze and Bazel.
- Introduction of StarlarkDocExpander: This new class is a proxy for the improved RuleLinkExpander as well as StarlarkDocUtils.substituteVariables(). As a result, Starlark documentation can now easily link to pages in the BE.
# Why JSON?
JSON is a lightweight configuration format, and luckily both Bazel and Blaze already have a JSON parser (GSON) among their dependencies.
# Downsides
The Starlark DocGen code is a love letter to the `static` modifier, which unfortunately means that we have to pass the StarlarkDocExpander instance through many methods.
# Alternatives
We could have passed the StarlarkDocExpander instance to the Velocity Template engine, which would have allowed us to call the expand() method from within the templates. However, I think it’s easier to figure out what happens if the real logic happens inside Java.
PiperOrigin-RevId: 433039776
{Fast, Correct} - Choose two
Build and test software of any size, quickly and reliably.
Speed up your builds and tests: Bazel rebuilds only what is necessary. With advanced local and distributed caching, optimized dependency analysis and parallel execution, you get fast and incremental builds.
One tool, multiple languages: Build and test Java, C++, Android, iOS, Go, and a wide variety of other language platforms. Bazel runs on Windows, macOS, and Linux.
Scalable: Bazel helps you scale your organization, codebase, and continuous integration solution. It handles codebases of any size, in multiple repositories or a huge monorepo.
Extensible to your needs: Easily add support for new languages and platforms with Bazel's familiar extension language. Share and re-use language rules written by the growing Bazel community.
Follow our tutorials:
To report a security issue, please email security@bazel.build with a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue. Our vulnerability management team will respond within 3 working days of your email. If the issue is confirmed as a vulnerability, we will open a Security Advisory. This project follows a 90 day disclosure timeline.
See CONTRIBUTING.md
