Need a registration hook for other plugins

[fralau]

As explained by @timvink in squidfunk/mkdocs-material#5933, writers of other plugins would need some hook to declare variables, macros and filters before the Mkdocs-Macros is actually run.

The rule adopted is following: three methods register_variables(), register_macros() and register_filters().

To facilitate work, these three method should work regardless of the order of declaration of plugins.

• The other plugin is declared before Mkdocs-Macros (its on_config() is run before MacrosPlugin.on_config()): they will be stored for later, and added last to the list of variables, macros or filters.
• The other plugin is declared after: they are immediately added to the list of variables, macros or filters.

In both cases, those keys are added on top of all other ones. Duplicate keys are not allowed and will cause a KeyError.

[fralau]

@timvink It's written. I have tested it roughly, so that I see that the code should work; but it would take me some time to build a test case.

Would you like to see if it works for you?

[timvink]

Sure, will try next week.

At the scale mkdocs-macros is at already, sure you don't write to write a unit test for this functionality, to ensure it keeps working in the future?

[fralau]

Sure, will try next week.

At the scale mkdocs-macros is at already, sure you don't write to write a unit test for this functionality, to ensure it keeps working in the future?

Yes. I have relied on testing my plugin on test websites (available), but I need to introduce a unit testing system.

In a few words, how do you go about unit-testing an mkdocs plugin, without using mkdocs serve (since it relies on MkDocs framework)?

[timvink]

You can test the functions / custom classes separately of course. I actually do prefer small 'integration' testing using mkdocs build.

What's worked for me is to build up a collection of small standalone examples (like here https://github.com/timvink/mkdocs-table-reader-plugin/tree/master/tests/fixtures) and test whether they fail (sometimes they should) or succeed, and whether the resulting html page(s) contain expected output. See f.e. https://github.com/timvink/mkdocs-table-reader-plugin/blob/master/tests/test_build.py

[fralau]

@timvink Thank you for these examples, this is very interesting!

[timvink]

Started having a look, and here's a first thing we can improve. I will need to implement it in a backwards compatible way, or at least require the user to upgrade to the latest version. So I want to know the version of macros plugin installed by the user.

Previously the convention was for python packages to have __version__ defined in the main __init__.py, so you can use package.__version__ to get the version. You can now do this dynamically by using this:

# __init__.py
import importlib.metadata

__version__ = importlib.metadata.version("mypackage")

But that will require you to move from setup.py to pyproject.toml first though. Soon pip will be updated to v25 and then things like editable installs for this plugin will start breaking, so that update will need to happen anyway. I've already upgraded some of my own plugins, for an example see https://github.com/timvink/mkdocs-table-reader-plugin/blob/master/pyproject.toml. Do note that this also then requires a different way to build your package (pip install build; python -m build or even better and way faster if you use uv: uv build)

For now I'll work around by testing to see if the register methods are available in table-reader.

[timvink]

Fixed it. See PR #238

Implemented in table reader here: timvink/mkdocs-table-reader-plugin#77 (I will wait for new macros release before releasing it table reader)

[fralau]

I passed the PR. Thanks a lot!

[fralau]

We now have a formal test in MkDocs-Macros for this development (test/register_macros)!

Which was what prompted the whole discussion about the testing framework in the first place (#244), leading to the creation of the MkDocs-Test plugin! 😮‍💨.

So we have gone full circle 🙂.