1**Last updated:** January 2021. 2 3**Summary:** We'll be redesigning how Stardoc works, and deprioritizing feature 4requests and minor bugs until that work is complete (targeting 2021 Q2). 5 6## Technical motivation 7 8Stardoc is currently the recommended tool for generating documentation of 9Starlark rules. It [replaces](skydoc_deprecation.md) *Sky*doc, the previous 10tool, which worked by evaluating .bzl files in a Python interpreter, using 11fake versions of functions from Bazel's Build Language. 12 13Mocking is an inherently problematic approach for two reasons: 14 151. It creates a maintenance burden for the tool maintainer (us). We have to 16ensure that the mocked definitions stay up-to-date as Bazel changes. These 17include not just `rule()` and `provider()`, but also a number of other symbols 18that don't directly affect documentation but still require stubs. 19 202. It puts a constraint on the user: All of their documented .bzl files, as 21well as all of the .bzl dependencies they transitively load, must be 22compatible with the mock evaluation. This means users must be vigilant about 23writing Starlark code that lies in the intersection of what is understood as 24valid by Bazel and by Stardoc. 25 26The Python-based Skydoc experienced an extreme version of this problem because 27it didn't even treat .bzl files as being written in the Starlark language. 28However, the Java-based Stardoc still uses mocking -- not of the Starlark 29language, but of Bazel's Build Language functions. 30 31In addition, Stardoc's mocking approach tightly integrates it with Bazel. 32Indeed much of its source code lives inside the bazelbuild/bazel repository. 33This makes refactoring and evolving the Bazel source code more difficult. 34 35While the Starlark language has a specification and several implementations, 36the Build Language is more complicated and has only one accurate 37implementation: Bazel. Any tooling that operates on BUILD and .bzl files must 38carefully consider whether it is feasible to ask Bazel for the authoritative 39information. The alternative, falling back on simulation, not only produces 40less accurate results, but ties our hands as we try to improve Bazel. 41 42## Our plans 43 44We will rewrite the part of Stardoc that extracts documentation information from 45.bzl files, so that instead of using mocking to pseudo-evaluate individual .bzl 46files, it performs a real Bazel evaluation of the workspace. Think of how `bazel 47query` is used to dump out information from Bazel's loading phase about the 48target dependency graph. Now imagine that it's extended to also dump out the 49rules and providers declared in the .bzl files used by a build, and that this 50dump also includes their docstrings. 51 52This approach intersects other work we are doing to simplify and better specify 53Bazel's loading phase, so that users have access to all sorts of information 54that was previously not readily available. 55 56Note that this new internal approach does not necessarily have to mean the 57user's workflow changes. You could still write a target in your BUILD file to 58say exactly what content you want documented and how you'd like it formatted. 59The rendering logic may very well continue to live outside of Bazel, in the 60bazelbuild/stardoc repository. 61 62## Prioritization 63 64We're aiming to explore this design in more concrete detail in 2021 Q1, and 65implement it in Q2. 66 67In the meantime, *we will not be focusing on improvements to the current 68implementation of Stardoc*, even the formatting parts which might remain the 69same. We still commit to keeping Stardoc working for its existing essential use 70cases. 71