Using Macros in Python Docstrings with Material for MkDocs

[nh916]

Hi everyone,

I'm currently working on documenting my Python package using Material for MkDocs, and I'm having a great experience with it so far.

One of the things I want to achieve is to use custom variables (macros) in my documentation to make it more maintainable. I have successfully used macros in my .md files, but I'm facing some challenges when trying to use them in my Python docstrings.

To clarify, in my .md files, I'm following the standard approach using macros, and it works like a charm:

# mkdocs.yaml
plugins:
  - macros

extra:
  homepage: https://my-website.org

<!-- my_file.md -->
[my link]({{ homepage }}/about/)

However, when I attempted to load macros from my Python docstrings, it didn't work as expected and it would output [my link]({{ homepage }}/about/)

Here's what I tried:

# mkdocs.yaml
plugins:
  - macros

extra:
  homepage: https://my-website.org

# some_module.py

class MyClass:
    """
    My class documentation.

    [my link]({{ homepage }}/about/)  # This doesn't work as it gets outputted literally as `{{ homepage }}`
    """
    pass

Thanks in advance for any assistance or suggestions you can offer!

[fralau]

Thanks for your question! (I hope I am tracking?)

Macros are designed to work in the markdown pages.

Mkdocs-macros renders the macros during on_page_markdown event (just before the Markdown rendering). I believe that mkdocstrings add the pages it on the on_env event, which is after all Markdown rendering and before HTML rendering (@pawamoy, the author of mkdocstrings will be able to confirm or invalidate what I say).

To include non markdown files, you may use the Jinja2 include directive. Include does render the file included (see the paragraph in mkdocs-macros).

[pawamoy]

@nh916 It's not clear from the description how you inject your documentation using mkdocstings, but regardless how you do it, Jinja markup in docstrings will not be rendered. @fralau is almost right: pages auto-generated with mkdocs-gen-files are generated during the on_files event. And anyway, mkdocstrings injects documentation from a Markdown extension, not a MkDocs plugin, so no MkDocs plugin will ever be able to "see" the docstrings and act on them. So, sorry, what you try to do is not possible 😕

But I think I recall a discussion about something similar. With enough hacks it could be made possible, however I don't think we have the necessary bits for it to work. I'll try to find that discussion again.

[fralau]

@pawamoy Thanks a lot for this clarification!

[fralau]

You can used fenced blocks, if necessary:

```python
{% include 'your_filename.ext' %}
```

See also my comment on mkdocs/mkdocs/discussions/3251