search

bazelbuild / stardoc

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

Do not HTML-escape and use Markdown inline code for defaults #161

Closed fmeum closed 1 year ago

fmeum commented 1 year ago

Reverts #133 so that HTML escaping is not applied to Markdown. Instead, Markdown content such as docstrings can use HTML formatting and escape angle brackets with backslashes, HTML entities or inline code segments. Default values are embedded in inline code segments instead of <code> tags, which does not require escaping.

As a result, docstrings behave just like regular Markdown contexts while default values are rendered without smart quotes and can contain both < and ` without causing escaping issues.

Also includes tests based on #138.

Fixes #137 Closes #138 Fixes #142 Closes #143

Requires https://github.com/bazelbuild/bazel/pull/18867

fmeum commented 1 year ago

@tetromino Could you review this PR? I created it when I noticed that updating Stardoc from 0.5.0 to 0.5.6 for Bzlmod compatibility broke my rulesets' docs (e.g. angle brackets in code blocks). I would really like to see Stardoc docs behave more similarly to other well-known Markdown contexts such as GitHub READMEs.

CC @illicitonion @adam-azarchs

tetromino commented 1 year ago

I agree with the PR in principle, but before reviewing and merging this, I want to move the markdown renderer java code here from the bazel repo and finally delete renderer_binary.jar instead of needing to keep updating it.

Work is in progress, give me (and my reviewers) a few days.

fmeum commented 1 year ago

Sounds good! I updated the PR to point to Bazel master and will happily make further changes post-move. Just mention me.

fmeum commented 1 year ago

@tetromino I rebased onto master including the move commit.

fmeum commented 1 year ago

@tetromino Thanks! It would be great if this could be included in a release soon to unblock rulesets that need to update for repo mapping support.

tetromino commented 1 year ago

@tetromino Thanks! It would be great if this could be included in a release soon to unblock rulesets that need to update for repo mapping support.

This release will break all existing golden markdown tests for Stardoc users. In order to minimize the frequency of such breakage, I want to additionally land the following breaking changes before cutting a release: