bazelbuild / bazelbuild/stardoc
Allow a new "Generated Targets:" section in Docstring
- 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
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