search

bazelbuild / stardoc

Stardoc: Starlark Documentation Generator
Apache License 2.0
108 stars 45 forks source link

Add support for lists in attribute docstrings in markdown renderer #118

Open aiuto opened 2 years ago

aiuto commented 2 years ago

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

foo|The attribute foo must be one of: - a: ... -b: ... | ...

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.

foo|The attribute foo must be one of: &lt;li&gt;a: ...

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).

aiuto commented 2 years ago

Possibly a dup of #78

brentleyjones commented 2 years ago

I just ran into this as well. There is no way to get this to render as a list 😢

tetromino commented 1 year ago

167 will allow html markup in table cells, so that one can at least work around the problem

alexeagle commented 1 year ago

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:

  • Include all TypeScript files in the package, recursively. - If allow_js is set, include all JavaScript files in the package as well. - If resolve_json_module is set, include all JSON files in the package, but exclude package.json, package-lock.json, and tsconfig*.json.

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 srcs list renders properly on https://docs.aspect.build/rules/aspect_rules_ts/docs/rules#srcs-1

aiuto commented 1 year ago

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.

alexeagle commented 1 year ago

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 😉