Resolve Variables from mkdocstrings

[kferrone]

I have a variable in the docstrings within code

def foo():
  """The foo func be like {{ some_var }}"""

then in the markdown

---
some_var: howdy dudes
---
::: mymod.myfile.foo

Is there a way to render variables that come in the output of other plugins?

[github-actions]

Welcome to this project and thank you!' first issue

[fralau]

In theory, that might work 🤔

As long, however, as the output of mkdocstrings is inserted into the page before Mkdocs-Macros does its magic.

Have you tried?

[kferrone]

I have been messing around with this a bit.
I tried with some hooks I made. I'm now having trouble getting a filter registered before the templates are rendered.

Here is some tests I'm playing with:

import logging, re
import mkdocs.plugins as plugins

log = logging.getLogger('mkdocs')

def my_filter(value):
    return "Hello there"

# this always runs too late, it complains the filter doesn't exist before running this event
# I think mkdocstrings is doing jinja stuff on their own before mkdocs gives the event
def on_env(env, config, files, **kwargs): 
    log.warning("Hello from one env!")
    env.filters['my_filter'] = my_filter
    return env

# This actually works for now
def on_page_content(html, page, **kwargs):
    return html.replace('{kind}', page.meta.get('kind', 'unknown'))

The on_page_content event seems to be late in the game enough. However, I'm not sure how to incorporate jinja magic here or do any kind of safe replacement of variables.

The on_page_markdown event happens very early on. Anything replaced here is before any of the plugins replace their stuff, ie mkdocstrings.

So maybe this plugin can run a bit later? What event does this plugin run during?

[fralau]

Have you tried writing a Mkdocs-Macros module in Python (main.py), and trigger events from there, using one of the hooks available?

💡 Tip: if all else fails you could use the env.render() method to interpret your Jinja2 template and then ouput it as the result of a macro (set force_rendering=True).

mkdocs-macros-plugin/mkdocs_macros/plugin.py

Lines 495 to 503 in 9a08f11

	def render(self, markdown: str, force_rendering:bool=False):
	"""
	Render a page through jinja2: it reads the code and
	executes the macros.
	It tests the `render_macros` metavariable
	in the page's header to decide whether to actually
	render or not (but you can force it).

[pawamoy]

As long, however, as the output of mkdocstrings is inserted into the page before Mkdocs-Macros does its magic.

It is not! At least not as mkdocs-macros would expect it. mkdocstrings works during Markdown conversion. MkDocs hooks never get to see the raw contents of docstrings.

I think mkdocstrings is doing jinja stuff on their own before mkdocs gives the event

Indeed, we use our own env.

To enable mkdocs-macros' features inside docstrings you will have to use a hack like this one: mkdocstrings/mkdocstrings#615 (comment) 🙂

[fralau]

@pawamoy My bad, I had forgotten about that... 😄

I am still in awe, because you might have a better understanding of Mkdocs-Macros, than I of mkdocstrings.