Mkdocs macro support in python

[emiliengarreau]

I saw that you provide support for mkdocs macro with the crystal handler.
Will it be available in python as well ?
Thanks

[pawamoy]

Sure, why not. What's your use case?

[emiliengarreau]

Sorry, for the delay.

I was speaking about:
https://mkdocstrings.github.io/crystal/extras.html#support-for-mkdocs-macros-plugin

In any case, I don't think you'll be able to use Jinja markup in your docstrings, because their contents do not pass through the MkDocs event hooks, they are directly rendered with Python-Markdown. So MkDocs Macros will not be able to render them.

That's what I thought at first but I saw support in mkdocs macro support in crystal documentation. I was intrigued on how you support it. I may have misread the functionalities of the support.

[pawamoy]

No problem! I see, thanks for the link. Well we can provide a pluglet as well that would expose the modules collection, but I'd like to see a use-case for it first. Otherwise if you just want to use MkDocs Macros in your docstrings without particularly using attributes from the Python handler... see the next pararaph:

Coming back to what I said previously: I'm not sure Jinja templating in docstrings would be rendered by MkDocs Macros. Looking at its code, the rendering seems to be done in the on_page_markdown event, when the docstrings have not yet been injected in the document. Maybe @fralau could confirm 🙂

[emiliengarreau]

Thanks for the answer 👍

[fralau]

Whoah! I hope I am tracking. Yes it is correct that the rendering of macros is done on the on_page_markdown event.

I can see that mkdocstrings does actions in the on_env event.

Just to make sure there is no confusion there, the Jinja2 templating of mkdocs is not the same thing as the Jinja2 templating of mkdocs-macro.

• The Jinja2 templating of mkdocs-macros is for rendering macros in markdown pages (on markdown event).
• The Jinja2 templating of mkdocs is for rendering HTML templates.

If you really wanted to make black magic, your Plugin (or whatever code) could exploit the rendering engine of mkdocs-macros (method render() of the class MacrosPlugin). With that method, you can render any string you please.

[pawamoy]

And mkdocstrings also have its own Jinja templating/env 🤣
If we somehow gave access to our mkdocstrings Jinja env, I guess users could indeed add mkdocs-macros' render method into it, and then override the docstrings templates to use that method. Dark magic as you point it 😄
Thanks for commenting @fralau!