| commit | bcf5b1753f745a323290a87dbb83734c40935c31 | [log] [tgz] |
|---|---|---|
| author | fwe <fwe@google.com> | Mon Mar 07 14:24:39 2022 -0800 |
| committer | Copybara-Service <copybara-worker@google.com> | Mon Mar 07 14:26:07 2022 -0800 |
| tree | ac19b910c513a4b48defab8a12d693bca2c40460 | |
| parent | cdc5d69942a2f7ee7a29f996c556d67ca44b296d [diff] |
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
