Stardoc generates repository.md

[alexeagle]

This is a mirror of the content in repository.rst, allowing us to manually inspect the delta between them:
LHS https://github.com/bazelbuild/bazel-gazelle/blob/master/repository.rst
RHS https://github.com/aspect-dev/bazel-gazelle/blob/stardoc/repository.md

As soon as we are satisfied that the generated content is correct, we'll delete repository.rst and update any links to it.
(This could happen as part of this PR, or subsequent)

Technique: copied doc strings out of existing rst file into the starlark files. Transcribed rst syntax to markdown.

First step in addressing #763
Remaining steps will be to rinse-and-repeat for other .rst files containing rule APIs

[achew22]

I think this is a great start! Thanks for doing this. The first thing that jumps out to me is that your .md version has git_repository first. That is deprecated and I suspect that most readers are at best skimming this document. Is there any way to reorder it so that the go_repository rule comes first?

[alexeagle]

yup, I noticed the same thing while diffing them.

even with stardoc given

symbol_names = [
    "go_repository",
    "git_repository",
    "http_archive",
],

they still appear alphabetically in the generated file. So I don't think this is possible with stardoc's current public API

[alexeagle]

FWIW the page does start with an index of the rules, and links to them, so the hurried reader might click the go_repository link and not get lost in the deprecated rule

[achew22]

LGTM, thanks @alexeagle. This is a huge step in the right direction for the repo. We should consider following up with a 302 or a link in the .rst file