feat(buildozer): add documentation for the buildozer rule

[sudoforge]

This patch introduces Stardoc to this workspace, and adds a series of targets that ultimately generate an output containing the rule reference for //buildozer:def.bzl%_buildozer, stripping the underscore for a nicer user experience.

It's difficult to say whether or not this is the best way to go about this, as what we're really doing is generating documentation for a private symbol (_buildozer), and then defining a genrule to invoke sed and remove the offending underscore. This rule is private because we expose the rule through a public macro buildozer, however, stardoc is incapable of generating complete documentation for the macro (including attributes from the proxied rule, which is what we'd want for friendly documentation -- see https://github.com/bazelbuild/stardoc/issues/82).

[sudoforge]

This patch also lacks tooling for easy updating of the documentation as I'm not sure how/if you'd prefer that -- a simple shell script would do the trick:

bazel build //buildozer/docs
cat $(bazel info bazel-bin)/buildozer/docs/buildozer_rule.md > buildozer/docs/buildozer_rule.md

[sudoforge]

The documentation needs to be regenerated if this is merged in after #107.

[ash2k]

This patch also lacks tooling for easy updating of the documentation as I'm not sure how/if you'd prefer that

Maybe add a makefile in the root of the repo with the script and add a note on how to update/regenerate the documentation in buildozer/README.md?

[sudoforge]

Maybe add a makefile in the root of the repo with the script and add a note on how to update/regenerate the documentation in buildozer/README.md?

Done. As stardoc is integrated with other parts of this repository, note that it may be preferred to write a rule that performs these actions outside of the context of the sandbox.

[ash2k]

Thanks!

[sudoforge]

We forgot to update the rule reference per my earlier comment :fearful:

I sent #108 to resolve this.