Allow using macros in docstrings (#687)

According to @pawamoy:

> `mkdocs-macros` and `mkdocstrings` work at different levels:
`mkdocs-macros` at the plugin level (in something like the
`on_page_markdown` hook) while `mkdocstrings` renders docstrings at the
Markdown conversion level, so in-between `on_page_markdown` and
`on_page_content`. That means `mkdocs-macros` never sees the docstrings.

To fix this, we can implement a hack to plug both together in the
`define_env()` function for `mkdocs-macros`.

Eventually a `mkdocs-macros` *pluglet* might be implemented so that this
hack is not necessary anymore.

For more context see:

* mkdocstrings/mkdocstrings#615

Author: llucax

docs/_scripts/macros.py

@@ -4,7 +4,9 @@
 """This module defines macros for use in Markdown files."""
 
 import pathlib
+from typing import Any
 
+import markdown as md
 from markdown.extensions import toc
 from mkdocs_macros import plugin as macros
 
@@ -56,3 +58,30 @@ def glossary(term: str) -> str:
         glossary_path = pathlib.Path("intro/glossary.md")
         link_path = glossary_path.relative_to(current_path.parent)
         return f"[{term}]({link_path}#{_slugify(term)})"
+
+    # The code below is a temporary workaround to make `mkdocs-macros` work with
+    # `mkdocstrings` until a proper `mkdocs-macros` *pluglet* is available. See
+    # https://github.com/mkdocstrings/mkdocstrings/issues/615 for details.
+
+    # get mkdocstrings' Python handler
+    python_handler = env.conf["plugins"]["mkdocstrings"].get_handler("python")
+
+    # get the `update_env` method of the Python handler
+    update_env = python_handler.update_env
+
+    # override the `update_env` method of the Python handler
+    def patched_update_env(markdown: md.Markdown, config: dict[str, Any]) -> None:
+        update_env(markdown, config)
+
+        # get the `convert_markdown` filter of the env
+        convert_markdown = python_handler.env.filters["convert_markdown"]
+
+        # build a chimera made of macros+mkdocstrings
+        def render_convert(markdown: str, *args: Any, **kwargs: Any) -> Any:
+            return convert_markdown(env.render(markdown), *args, **kwargs)
+
+        # patch the filter
+        python_handler.env.filters["convert_markdown"] = render_convert
+
+    # patch the method
+    python_handler.update_env = patched_update_env

mkdocs.yml

@@ -88,10 +88,6 @@ plugins:
         - docs/_scripts/mkdocstrings_autoapi.py
   - literate-nav:
       nav_file: SUMMARY.md
-  - macros:
-      module_name: docs/_scripts/macros
-      on_undefined: strict
-      on_error_fail: true
   - mike:
       canonical_version: latest
   - mkdocstrings:
@@ -119,6 +115,13 @@ plugins:
             - https://protobuf.readthedocs.io/en/latest/objects.inv
             - https://typing-extensions.readthedocs.io/en/stable/objects.inv
             - https://watchfiles.helpmanual.io/objects.inv
+  # Note this plugin must be loaded after mkdocstrings to be able to use macros
+  # inside docstrings. See the comment in `docs/_scripts/macros.py` for more
+  # details
+  - macros:
+      module_name: docs/_scripts/macros
+      on_undefined: strict
+      on_error_fail: true
   - search
 
 # Preview controls