Handlebars spills through into API viewer #1873
Comments
KitsuneRal
added
the
aesthetic
|
fwiw, I did this deliberately to improve readability of the rendered spec - the fallback to text isn't great, but still readable enough. I prefer we stay away from |
Namely, GTAD itself had to be updated to support patternProperties and
mx-* format names; and gtad.yaml now substitutes `{{% boxes/note %}}`
with a Doxygen \note tag (see also
matrix-org/matrix-spec#1873).
|
Okay, I think I agree with the rationale. That makes for an interesting precedent of using a more structured markup layer over Markdown - I wonder if there was prior art here, we are likely not the first ones stumbling over it. I don't seem to find anything quickly though. In the meantime, what we could do then is to replace handlebars with Markdown when preparing a consolidated API description for the API Viewer; and owners of other generated code can do replacements that work best for them (e.g. for Quotient I would replace handlebars with Doxygen tags in generated C++ code). |
- GTAD itself had to be updated to support patternProperties and
mx-* format names
- gtad.yaml now substitutes `{{% boxes/note %}}` with a Doxygen \note
tag (see also matrix-org/matrix-spec#1873)
- endpoint deprecation is supported now (desirable for content-repo.*
to make the message about moving to authed media very clear).
KitsuneRal
changed the title
Link to problem area:
https://github.com/matrix-org/matrix-spec/blob/main/data/api/client-server/content-repo.yaml#L226 and elsewhere in the same file.
Issue
API description files can be used by code generation tools, and our own API viewer consumes them. While it's still sort of readable through the handlebars, I'd rather stick to Markdown in API files.
The text was updated successfully, but these errors were encountered: