feature: Jinja handler

[pawamoy]

Is your feature request related to a problem? Please describe.

No standard way to document Jinja templates?

Describe the solution you'd like

I just realized it would be nice to have a handler for documenting and auto-generating docs for Jinja templates.
It would parse the templates and extract information from Jinja comments for macros, filters, tests and context.

Describe alternatives you've considered

Manually written Markdown docs.

Additional context

Would be super useful for handlers themselves!

[pawamoy]

I'm writing comments to the Python handler templates so this might be a good time to think about how to format them for easy retrieval and use.

What kind of information should be retrievable from Jinja templates?

• available context: variables (name, type, value), functions (name, signature, they're variables too), filters (name, signature), tests (name, signature)
• declared variables (with set, for example with block assignment)
• available blocks: whether they are scoped or required, blocks inherited from parent templates
• available tags (loaded through extensions) and their signature?
• template inheritance diagrams (extends)
• template inclusion diagrams (include)
• template imports diagrams (import)
• a combination of those? (extends + include?)
• declared macros, whether they use their caller and how
• extension-specific: for HTML templates, CSS classes used (and in what elements they are used? to build precise selectors?), or summarized HTML tree (div, h2, p, div, ...)

[pawamoy]

Hmm, available context (variables, functions, filters, tests, tags) cannot be fully inferred from static analysis only. But I don't see how we could use dynamic analysis, unless we profile the tool and its code rendering templates (I don't think that's feasible, or that it makes much sense anyway). For a complete list of what's available, template writers might need to document that in the template itself.

[pawamoy]

I'll mark both our comments as off-topic (this issue is really about documenting Jinja templates, not Markdown/HTML (pre-)processing), I hope you won't mind 🙂 Feel free to open a dedicated discussion instead 🙂

[tomchristie]

Ah yep, understood. 👍🏼