-
Notifications
You must be signed in to change notification settings - Fork 44
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Stardoc for targets #108
Comments
I'm not sure what form this should take or if this should be part of bazel itself instead of just the stardoc tool. For example, if rules themselves all had an optional doc attribute, then the documentation could be queried interactively using bazel query. The stardoc tool could then pull this information and the rule information to assemble documentation for the entire package, which can be pulled into a larger document generation system. |
I can see documentation for targets making sense, particularly for config_settings and build_settings, and maybe for toolchains too. We'd have to decide on a syntax, expose it through bazel, and update stardoc to consume it. |
+1 to doing this for config_setting. It is the first step in being able to retain documentation for flags that migrate from native bazel to starlark. |
Sometimes the target's name and rule kind don't provide much detail on its purpose. When should the target be used? Is it runnable, testable, or just buildable? Maybe it's meant only to be used as part of a larger dependency?
This kind of information along with details that come from the rule could be a good source of documentation for a package, especially for newcomers. Imagine looking through a BUILD.bazel file with a bunch of sh_binary() targets. This could seem very opaque without some context.
The text was updated successfully, but these errors were encountered: