Allow a new "Generated Targets:" section in Docstring

[jerechua]

It would be nice to be able to specify and generate some simple documentation for public targets generated by macros. In my head this looks something like:

def my_macro(name):
  """My macro summary.
  
  Args:
    name: The name of my macro.

  Generated Targets:
    :<name>: The main target description.
    <name>_secondary: The secondary target description.
  """
  my_rule(name = name)
  my_rule(name = "%s_secondary" % name)

As opposed to crawling through the macro to figure out documentation that needs to be generated for rules within. Mainly because it would could be annoying to figure out names that are string replaced and not generating documentation for rules that are implementation details.

[c-parsons]

Hmm, I don't have a good sense of how many users would care to have this consistently generated (hence meriting a whole section for Generated Targets) versus those who would be fine with describing the generated targets in the normal doc string section. About how many of your team's macros would be helped by this functionality?

[jerechua]

All our build macros generate metadata files about the build on top of the thing that needs to be built (in the 10s of build macros). We mostly care about other folks that are unfamiliar with the system to be able to find and build those metadata files.

I have tried adding a new block to the docstring, but Stardoc doesn't seem too happy about parsing it when it's at the bottom of the docstring since it thinks it's a misplaced description paragraph. Maybe it's not so bad to add it as paragraph, but we lose any chance of prettifying that section and it will sorely appear above the Args: section in code.

As per your suggestion on generating protos in https://github.com/bazelbuild/skydoc/issues/120, perhaps the docstring AST can be generalized, where it outputs a section_name and a custom "Generated Targets" section wouldn't matter too much since we'd handle that.