bazelbuild / bazelbuild/stardoc

Allow a new "Generated Targets:" section in Docstring

Open
#32 2 comments 2 reactions 0 assignees View on GitHub
P4 type: feature request
Dominant language
Java
Stars
118
Forks
51
PR merge metrics
No merged PRs in 30d

Description

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:
:: The main target description.
_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.

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are named. Start by locating the docstring parser and generated-target documentation path, then define the proposed section syntax and expected output before implementation. Done means public targets described in the new section receive documentation without requiring macro crawling.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.