Skip to content

This issue was moved to a discussion.

You can continue the conversation there. Go to discussion →

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Resolve Variables from mkdocstrings #233

Closed
kferrone opened this issue Jul 17, 2024 · 6 comments
Closed

Resolve Variables from mkdocstrings #233

kferrone opened this issue Jul 17, 2024 · 6 comments
Labels
useful tip A how-to, good to know

Comments

@kferrone
Copy link

kferrone commented Jul 17, 2024

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?

Copy link

Welcome to this project and thank you!' first issue

@fralau
Copy link
Owner

fralau commented Jul 17, 2024

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
Copy link
Author

kferrone commented Jul 17, 2024

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
Copy link
Owner

fralau commented Jul 18, 2024

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

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

@fralau fralau added the useful tip A how-to, good to know label Jul 18, 2024
@pawamoy
Copy link

pawamoy commented Jul 20, 2024

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
Copy link
Owner

fralau commented Jul 20, 2024

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

Repository owner locked and limited conversation to collaborators Jul 20, 2024
@fralau fralau converted this issue into discussion #235 Jul 20, 2024

This issue was moved to a discussion.

You can continue the conversation there. Go to discussion →

Labels
useful tip A how-to, good to know
Projects
None yet
Development

No branches or pull requests

3 participants