Add support for lists in attribute docstrings in markdown renderer #118
Comments
|
Possibly a dup of #78 |
|
I just ran into this as well. There is no way to get this to render as a list 😢 |
|
#167 will allow html markup in table cells, so that one can at least work around the problem |
… apply it properly (#167) In Markdown table cells, apply HTML escaping only to code blocks, and apply it properly Since #161 removed HTML escaping for defaults and function docstrings, we should do the same for attribute and param docs in table cells. The only limitations Markdown places on table cells are: * no pipe characters (they must be escaped with a backslash) * no newlines (they must be transformed into `<br>` or an HTML entity) The latter restriction makes it impossible to have a fenced code block inside a table cell. Therefore: * we do not escape HTML or Markdown markup outside a fenced code block * we keep existing logic for escaping newlines outside a fenced code block * we fix fence detection (e.g. allowing more than 3 fence characters to support embedded code blocks in code blocks, allowing tildes as fence characters, properly handling language names, etc.); * in code block content, we escape HTML, and we escape newlines as HTML entities (since `<br>` does not work in a `<pre><code>` block) - finally fixing code block newlines in table cells. This is a followup to #161. Partially addresses #118
|
For Aspect's rulesets, our solution for this is to treat the stardoc markdown view as the "not very good presentation layer". For example https://github.com/aspect-build/rules_ts/blob/main/docs/rules.md#ts_project-srcs suffers from this problem, appearing as a paragraph that's possible but not easy to read:
Then we provide a much better documentation experience, akin to how https//:bazel.build documents the core Bazel libraries in a website rather than relying on stardoc markdown to produce a nice presentation on GitHub's UI. Ideally I think the Bazel project could host a docsite like https://about.readthedocs.com/ does for python or https://pkg.go.dev/ does for Go. But in the spirit of not waiting for Google, we already built that. Continuing that example above, you see the same |
|
Can you contribute that renderer level back to stardoc? It is so much more convenient to depend on one documentation tool rather than a fwe of them. |
|
I think it's pretty complicated to contribute since it's wired up with our docusaurus docsite and node-based rendering pipeline. Also every time I try to contribute here I get stuck pinging Googlers for a year, honestly I gave up, and I have more tenacity than most. Let's get a DevRel on the project 😉 |
I want to be able to write a docstring that presents as
The attribute foo must be one of:
The markdown renderer puts attributes in rows of a table, but does something like
That does not render correctly because the newlines are stripped.
The standard hack for this in markdown is to embed <li>, but then stardoc escapes the element.
I think the general principal is that if you are in one language (markdown) then you should not escape things as if it were the other language (HTML).
The text was updated successfully, but these errors were encountered: