bazelbuild / bazelbuild/stardoc

Fix list rendering in table cells

Open
#301 1 comment 1 reaction 0 assignees View on GitHub
P3 type: bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.