Stardoc over-escapes angle brackets in docstrings.

[adam-azarchs]

Unfortunately, while #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

stardoc/test/testdata/repo_rules_test/golden.md

Line 21 in 3feb2a9

| <a id="my_repo-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | |

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