Stardoc over-escapes angle brackets in docstrings.

[adam-azarchs]

Unfortunately, while https://github.com/bazelbuild/stardoc/pull/133 fixed a bunch of things, it also broke a bunch of other things. In particular, if one has a rule or respository rule with a doc attribute like

doc = """
Blah blah `<workspace_name>`
"""

it will be converted to

Blah blah `<workspace_name>`

which renders as

Blah blah <workspace_name>

The issue here, of course, is the mismatch between using HTML tags (e.g. <pre> or <code>) for formatting in some situations (e.g. tables), and native markdown formatting in others. One must use escaping in the former situation, but using it in the latter breaks stuff.

[alexeagle]

I think the <p> here https://github.com/bazelbuild/stardoc/blob/3feb2a931a040fb1a3b288839ba393dc341cd2e0/test/testdata/repo_rules_test/golden.md?plain=1#L21 is another case of this bug?

[adam-azarchs]

I think the <p> here

is another case of this bug?

This is somewhat different, as it's arguable that this is a bug in the source of that documentation rather than in the translation thereof, though the backwards-compatibility argument for saying it's a bug on this end is pretty strong. It's also a bit of an oddball case, since the docstring there is defined in Java rather than Starlark.

At any rate, we can't really expect it to be able to guess whether <p> means "I want a new paragraph" or "I want a <p> in the text"; we can only expect it to be consistent as to whether it's treating the input as markdown or as html.

[alexeagle]

Hm that's interesting that the two newlines in that doc string get lost as well. The paragraph tag shouldn't be needed if docs are markdown and there is a blank line in between.

[adam-azarchs]

I opened https://github.com/bazelbuild/stardoc/pull/138 to add some (failing) test cases demonstrating some of these problems. However unless I'm mistaken the code to fix this issue lives somewhere in the java code of https//github.com/bazelbuild/bazel, so it can't be fixed via a PR in this repo.