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[bot]]

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 Just to summarize: you are using an Mkdocs-Macros module to monkey patch update_env() from the python handler in mkdocstrings, so that it renders (later, at the approriate time) the macros contained in the strings of Python code.

This approach is simple and clean and indeed, I would encourage developers to use and abuse the MacrosPlugin.render() method (note: if you want to be sure it will always render regardless of what Mkdocs-Macros would normally do, you might want to set force_rendering to True).

I am not sure I fully grasped the meanders of the calls to to the mkdocstrings plugin, but that is the gist, isn't it?

[pawamoy]

Seems like you got it, yes :)

[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.

[fralau]

I converted this into a discussion, since it was more appropriate.

[kferrone]

I did figure this out my own way in a mkdocs hooks file. Not the easiest thing to figure out. I now know way too much about mkdocs and mkdocstrings. It for sure works now though.

Basically here is the process.

mkdocs.py

from jinja2.filters import FILTERS

page_meta = None

def page_meta_filter(input):
  """Filter to access page meta data in markdown"""
  t = Template(input)
  return t.render(**page_meta)

def on_startup(**kwargs):
  # this is the only way I could possibly get jinja to pick up the filter
  # using any option built into mkdocs all happened too late 
  FILTERS['page_meta'] = page_meta_filter
  
def on_page_markdown(markdown, page, config, **kwargs):
  """Save the page meta data to be used in the page_meta_filter"""
  global page_meta
  page_meta = page.meta
  return markdown

within the mkdocs.yml

hooks:
- mkdocs.py

Then the hardest part to figure out. I had to extend the templates themselves from here: https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/material

I added this file in my docs dir like docs/templates/python/material/docstring.html.jinja
I copied all the contents of this file into mine: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html

Here is what I changed it to:

{% if docstring_sections %}
  {% block logs scoped %}
    {#- Logging block.
    
    This block can be used to log debug messages, deprecation messages, warnings, etc.
    -#}
    {{ log.debug("Rendering docstring") }}
  {% endblock logs %}
  {% for section in docstring_sections %}
    {% if config.show_docstring_description and section.kind.value == "text" %}
      {{ section.value|page_meta|convert_markdown(heading_level, html_id) }}
    {% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
      {% filter page_meta %}
        {% include "docstring/attributes"|get_template with context %}
      {% endfilter %}
    {% elif config.show_docstring_functions and section.kind.value == "functions" %}
      {% include "docstring/functions"|get_template with context %}
    {% elif config.show_docstring_classes and section.kind.value == "classes" %}
      {% include "docstring/classes"|get_template with context %}
    {% elif config.show_docstring_modules and section.kind.value == "modules" %}
      {% include "docstring/modules"|get_template with context %}
    {% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
      {% filter page_meta %}
        {% include "docstring/parameters"|get_template with context %}
      {% endfilter %}
    {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}
      {% filter page_meta %}
        {% include "docstring/other_parameters"|get_template with context %}
      {% endfilter %}
    {% elif config.show_docstring_raises and section.kind.value == "raises" %}
      {% include "docstring/raises"|get_template with context %}
    {% elif config.show_docstring_warns and section.kind.value == "warns" %}
      {% include "docstring/warns"|get_template with context %}
    {% elif config.show_docstring_yields and section.kind.value == "yields" %}
      {% include "docstring/yields"|get_template with context %}
    {% elif config.show_docstring_receives and section.kind.value == "receives" %}
      {% include "docstring/receives"|get_template with context %}
    {% elif config.show_docstring_returns and section.kind.value == "returns" %}
      {% filter page_meta %}
        {% include "docstring/returns"|get_template with context %}
      {% endfilter %}
    {% elif config.show_docstring_examples and section.kind.value == "examples" %}
      {% include "docstring/examples"|get_template with context %}
    {% elif config.show_docstring_description and section.kind.value == "admonition" %}
      {% include "docstring/admonition"|get_template with context %}
    {% endif %}
  {% endfor %}
{% endif %}

Some pydocs

def foo():
  """Hello {{ someone }}"""
  return "Hell world"

My markdown:

---
someone: Mr Docs
---
::: mypackage.mymod.foo

[pawamoy]

Wow, thanks for sharing! Quite a nice solution. I'll keep that FILTERS in mind.