Skip to content

Handler plugin registration from anywhere #163

@axgkl

Description

@axgkl

Hi Timothy,

Is your feature request related to a problem? Please describe.

I want to create a specific handler in my project but I found only hackish ways to hook it in, so that mkdocstrings finds and imports it (either by copying the module into the handlers directory before mkdocs builds or by at docu runs import mine before and it hammers itself into your handlers_cache ... Not nice...

Problem is that you seem to import only from your own handlers directory (module =importlib.import_module(f'mkdocstrings.handlers.{name}')).

Describe the solution you'd like

Would be cool if I could say in an md file: handler: myproject.doc_support.my_pytest_result_handler.
I.e. that you detect dotted paths and try import not only from mkdocstrings.handlers but from current sys.path, when it is a dotted path.

Describe alternatives you've considered
I symlink my custom handler over to mkdocs dir, before starting mkdocs.


Another possible enhancement on the topic of custom handlers I may suggest:

I realized that for what I want to do (enriching the information delivered from the subprocess by code analysis with some information written into files while running pytest): The best to hook in my custom stuff is in the rebuild_category_lists recursion.
Here you have all information and can rather straightforwardly add custom infos, right? Plus its a nice and small function easy enough to customify.
So it may be nice also for others to be able to inject a custom function here, for example in the get_handler function of a custom module:

    return python.PythonHandler(
        collector=python.PythonCollector(setup_commands=setup_commands),
        renderer=python.PythonRenderer('python', theme, custom_templates),
        builder=my_recursive_builder # (optional)
    )

Right now I have to hammer it in via a monkey patch:

from mkdocstrings.handlers import python
python.orig_rebuild = python.rebuild_category_lists
python.rebuild_category_lists = rebuild_category_lists

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions