Add docs:update target

[keith]

This can be run with bazel run docs:update to copy over changes.

[keith]

I noticed we're not putting all the other cc_binary etc stardoc generations in the docs/ directory, i assume because they're also on the website? i wonder if we should generate them here too just for easier discovery for people who are already looking at this repo

[lilygorsheneva]

i wonder if we should generate them here too just for easier discovery for people who are already looking at this repo

I think that's a good idea.

(the file in #701 would need a rename, haven't looked closely at that PR yet)

[trybka]

Wonder if @meteorcloudy or @Wyverald have any thoughts? I'm a bit more in the dark on doc things

[Wyverald]

I don't have much to offer here -- different rulesets have very different ways of serving documentation; some use just GitHub, others use stuff like readthedocs. Maybe the future is the automatic doc extraction from the new BCR UI (e.g. https://registry-preview.bazel.build/modules/rules_cc/0.2.18/docs/cc/toolchains/impl/documented_api.bzl/cc_tool)?

[trybka]

I don't have much to offer here -- different rulesets have very different ways of serving documentation; some use just GitHub, others use stuff like readthedocs.

I think it's more of a policy / intent question.

When rulesets originate from Bazel as builtins, and then they "graduate" to their own Rulesets, how do we want to handle those?

What have we done for other rulesets (proto, java, etc.)?

[Wyverald]

Nothing centrally managed has happened (not that I know of anyway). The sorry state of affairs is plainly visible if you look at the "language-specific rules" section of the Bazel Build Encyclopedia (https://bazel.build/reference/be/java for example). IMO ideally there would be a well-lit path for docs serving for all rulesets (not just the ones that 'graduated' from Bazel) -- hence why I suggested just congregating on the BCR UI; but that's not a great solution for prose docs.

I think the most readily achievable thing for now is for each ruleset to put some generated .md files in the same directory so that they're viewable from GitHub at least (rules_go does this quite well: https://github.com/bazel-contrib/rules_go/blob/master/docs/go/core/rules.md). This PR is a good step towards that.

[armandomontanez]

+1, I'd like to see the BCR reference docs be the long-term future (a la rustdoc) as well, but I think markdown files are immediately helpful.