Open Oberon00 opened 3 years ago
In addition, it would be very helpful if there were a way to change links from being markdown to being standard html links.
@jkwatson I did not know myself, but we already merged support for that: https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/src/opentelemetry/semconv/templating/code.py#L28
@jkwatson I did not know myself, but we already merged support for that: https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/src/opentelemetry/semconv/templating/code.py#L28
I looked through the code a bunch last week, but isn't that method for "rendering markdown", not the jinja templates?
That function is made available to the code generator template here: https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/src/opentelemetry/semconv/templating/code.py#L204
So you should be able to do {{attr.brief | render_markdown()}}
in the Jinja template.
That function is made available to the code generator template here: https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/src/opentelemetry/semconv/templating/code.py#L204
So you should be able to do
{{attr.brief | render_markdown()}}
in the Jinja template.
I'll give it a whirl and see how it goes. I never would have found that particular bit of code, or had any idea how to use it. Thanks for the pointer!
Yeah, the docs are lacking 😔
Unfortunately, render_markdown
doesn't render it in a javadoc-friendly manner. it escapes all the html tags, even ones that are good for javadoc (<p>
and <code>
for instance). Is there a magic way to stop that from happening?
It looks like you might be able to pass in a function for formatting the particular bits...not sure how to call that from a jinja template, but I'm still poking at it.
I got something sort-of working: https://github.com/open-telemetry/opentelemetry-java/pull/3394
We discussed some of this in a recent small-group on Semantic Convention Tooling. I think we'll need to tear this feature request into pieces, but a few points:
Given this - I think we should split this feature request apart between "internal" and "spec" links.
Specifically:
See https://github.com/open-telemetry/opentelemetry-specification/pull/1192
The markdown generator would need to be passed an URL prefix that is treated as root which is relatively linkable. Semantic conventions would contain absolute links (i.e. revert that part of https://github.com/open-telemetry/opentelemetry-specification/pull/1192).
Other generators should support replacing an URL prefix e.g.
https://github.com/open-telemetry/opentelemetry-specification/tree/master/
tohttps://github.com/open-telemetry/opentelemetry-specification/tree/v0.6/
.