bazelbuild / bazelbuild/stardoc
Fix list rendering in table cells
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
If you have a rule attribute with a doc string containing a list:
```bzl
{
"foo": attr.string(default = "x", values = ["x", "y"], doc = """Blah blah blah
Possible values:
* `"x"` - sets foo to x
* `"y"` - sets foo to y
"""),
}
```
then Stardoc will misrender it in a cell of the rule attributes table, producing something terrible and ugly like
```md
| Blah blah blah
Possible values: * `"x"` - sets foo to x * `"y"` - sets foo to y |
```
Example: https://github.com/bazelbuild/bazel-skylib/pull/587
Instead, we want to transform Markdown lists into HTML - same as we already do for code blocks (see `formatFencedCodeBlock` in `MarkdownUtil.java`).
The desired output should be something like
```md
| Blah blah blah
Possible values:
- `"x"` - sets foo to x
- `"y"` - sets foo to y
```
See also https://stackoverflow.com/questions/19950648/how-to-write-lists-inside-a-markdown-table
Contributor guide
Research direction
Start by reading MarkdownUtil.java and the existing formatFencedCodeBlock logic. Trace how Markdown in rule attribute documentation is rendered into table cells, then verify that list syntax produces HTML list elements in the generated table output shown in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100