feat(buildozer): add documentation for the buildozer rule

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 bazelbuild/stardoc#82).

Makefile

@@ -0,0 +1,8 @@
+bazel_bin_dir=$(shell bazel info bazel-bin)
+
+.PHONY: buildozer/docs
+buildozer/docs:
+	@/usr/bin/env bazel build //buildozer/docs
+	@/usr/bin/env cat \
+		$(bazel_bin_dir)/buildozer/docs/buildozer_rule.md >\
+		buildozer/docs/buildozer_rule.md

WORKSPACE

@@ -35,6 +35,16 @@ git_repository(
     shallow_since = "1581711200 -0800",
 )
 
+# Stardoc is a documentation generator for Bazel
+http_archive(
+    name = "io_bazel_stardoc",
+    sha256 = "74f4b76a6307f1543c2f974236db2aee86bdcf55dbc41a16bb518e1ffa939644",
+    strip_prefix = "stardoc-a8c608986b4f27416ce085495617a6c9b3b40195",
+    urls = [
+        "https://github.com/bazelbuild/stardoc/archive/a8c608986b4f27416ce085495617a6c9b3b40195.tar.gz",
+    ],
+)
+
 load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
 load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies")
 load("@com_github_bazelbuild_buildtools//buildifier:deps.bzl", "buildifier_dependencies")

buildozer/BUILD.bazel

@@ -1 +1,9 @@
 exports_files(["runner.bash.template"])
+exports_files(
+    [
+        "def.bzl",
+    ],
+    visibility = [
+        "//buildozer/docs:__pkg__",
+    ],
+)

buildozer/README.md

@@ -52,3 +52,12 @@ Invoke with
 ```bash
 bazel run //:buildozer
 ```
+
+## Documentation
+
+- Buildozer [rule reference](docs/buildozer_rule.md)
+
+## Contributor notes
+
+* After updating the `_buildozer` rule's inline documentation, you should run
+  `make buildzer/docs` from the repository root.

buildozer/docs/BUILD.bazel

@@ -0,0 +1,32 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+
+bzl_library(
+    name = "buildozer_docs_library",
+    srcs = [
+        "@bazel_skylib//lib:shell.bzl",
+    ],
+)
+
+stardoc(
+    name = "buildozer_rule_docs",
+    input = "//buildozer:def.bzl",
+    out = "buildozer_rule.in.md",
+    deps = [
+        ":buildozer_docs_library",
+    ],
+    symbol_names = [
+        "_buildozer",
+    ],
+)
+
+genrule(
+    name = "docs",
+    srcs = [
+        ":buildozer_rule_docs",
+    ],
+    outs = [
+        "buildozer_rule.md",
+    ],
+    cmd = "sed -e 's/_buildozer/buildozer/g' $(location :buildozer_rule_docs) > $@",
+)

buildozer/docs/buildozer_rule.md

@@ -0,0 +1,35 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+<a id="#buildozer"></a>
+
+## buildozer
+
+<pre>
+buildozer(<a href="#buildozer-name">name</a>, <a href="#buildozer-add_tables">add_tables</a>, <a href="#buildozer-buildifier">buildifier</a>, <a href="#buildozer-commands">commands</a>, <a href="#buildozer-delete_with_comments">delete_with_comments</a>, <a href="#buildozer-edit_variables">edit_variables</a>,
+           <a href="#buildozer-error_on_no_changes">error_on_no_changes</a>, <a href="#buildozer-format_on_write">format_on_write</a>, <a href="#buildozer-keep_going">keep_going</a>, <a href="#buildozer-prefer_eol_comments">prefer_eol_comments</a>, <a href="#buildozer-quiet">quiet</a>,
+           <a href="#buildozer-shorten_labels">shorten_labels</a>, <a href="#buildozer-tables">tables</a>, <a href="#buildozer-types">types</a>)
+</pre>
+
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="buildozer-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="buildozer-add_tables"></a>add_tables |  JSON file with custom table definitions which will be merged with the built-in tables   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="buildozer-buildifier"></a>buildifier |  A label pointing to an executable buildifier output. Has no meaning unless <code>format_on_write</code> is True   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="buildozer-commands"></a>commands |  File to read commands from   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
+| <a id="buildozer-delete_with_comments"></a>delete_with_comments |  If a list attribute should be deleted even if there is a comment attached to it   | Boolean | optional | True |
+| <a id="buildozer-edit_variables"></a>edit_variables |  For attributes that simply assign a variable (e.g. hdrs = LIB_HDRS), edit the build variable instead of appending to the attribute   | Boolean | optional | False |
+| <a id="buildozer-error_on_no_changes"></a>error_on_no_changes |  Exit with 3 on success, when no changes were made   | Boolean | optional | False |
+| <a id="buildozer-format_on_write"></a>format_on_write |  Set to True for format on write using the -buildifier flag. If the <code>buildifier</code> attribute is empty, use the built-in formatter   | Boolean | optional | False |
+| <a id="buildozer-keep_going"></a>keep_going |  Apply all commands, even if there are failures   | Boolean | optional | False |
+| <a id="buildozer-prefer_eol_comments"></a>prefer_eol_comments |  When adding a new comment, put it on the same line if possible   | Boolean | optional | True |
+| <a id="buildozer-quiet"></a>quiet |  Suppress informational messages   | Boolean | optional | False |
+| <a id="buildozer-shorten_labels"></a>shorten_labels |  Convert added labels to short form, e.g. //foo:bar =&gt; :bar   | Boolean | optional | True |
+| <a id="buildozer-tables"></a>tables |  JSON file with custom table definitions which will replace the built-in tables   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="buildozer-types"></a>types |  List of rule types to change, the default empty list means all rules   | List of strings | optional | [] |
+
+