3.0: drop stardoc

[alexeagle]

https://github.com/bazel-contrib/bazel-lib/blob/main/lib/docs.bzl relies on the stardoc module, which has a big fat dependency list, doesn't work with Bazel 6, and more. See "Legacy WORKSPACE Setup" https://github.com/bazelbuild/stardoc/releases/tag/0.8.0 for the ugliness.

Rules_go has their own stardoc_with_diff_test https://github.com/bazel-contrib/rules_go/blob/master/docs/doc_helpers.bzl
so we know users could just do this themselves.

We no longer use this rule ourselves since we can publish docs for BCR to render, see bazel-contrib/rules-template#160 and my upcoming blog post https://hashnode.com/draft/68dc18b3df4b794c7b0074a6

Perhaps we move it to the stardoc repo, or just delete it with no replacement.

@fmeum @malt3 FYI

[malt3]

Thanks for the heads up! I do intend to keep something like this around as I find generated markdown useful in my rulesets.
Happy to add it myself downstream where needed.

[fmeum]

Moving it to the state of repo sounds ideal to me as it's useful for anyone who uses stardoc directly.

@tetromino What do you think?

[tetromino]

Please feel free to drop the dep from bazel-lib :)

Packaging something like this with Stardoc does make sense. There are probably a dozen similar stardoc updater macros floating around, so rather than just copying the bazel-lib one, perhaps it makes sense to design something with the best features of all of them.

Some things that immediately come to mind:

• There should be a test target to compare the .md output in the source tree with the generated output (bazel-lib's stardoc_with_diff_test doesn't do this, but, based on the name, I am guessing that it used to do this in the past)
• ... but Stardoc output is sensitive to Bazel version. Which means such a test should be tagged manual by default - or your bazel test //... will break whenever you switch Bazel versions.
• ... and if the test fails, it should output an error message explaining that you probably need to bazel run $updater (and pay attention which bazel version you use when running it).
• Would be nice if the test allows changing the diffing tool and/or preprocessing the inputs

[alexeagle]

Thanks @tetromino - sent you bazelbuild/stardoc#303 to upstream this.