Is it possible to override template files for plugins?

[Andre601]

I'm using neoteroi.mkdocsoad to generate docs from Open API specifications... And after looking a bit into it did I notice that the tool it uses - essentials-openapi - apparently utilizes Jina2 templating for MkDocs-style documentation.

I now wonder: Can I somehow override the used template files of the plugin to customize some of its output?
If I can, are there ways to figure out the effective path of a template file, so that I could override them?

I also asked in the essentials-openapi repository, but given the maintainer's recent activity here on GitHub I have doubts to receive any reply to it...
Worst case I have to create a forked version of the plugin to modify it... Which opens a whole can of worms I would love to keep closed as I'm not ready yet to tackle Python and MkDocs plugins...

One alternative I've been thinking about here is to maybe use templating itself with the openapi file? Would that be a thing to work with?

[oprypin]

This question is 100% specific to the plugin. But just pointing that out, it's not forbidden to ask.

essentials-openapi seems pluggable, you'd just provide your own package with themes.
https://github.com/Neoteroi/essentials-openapi/blob/6bbd8c51934c65ec2c315797f6fb4b64bba14dc8/openapidocs/mk/v3/__init__.py#L101
https://github.com/Neoteroi/essentials-openapi/blob/6bbd8c51934c65ec2c315797f6fb4b64bba14dc8/openapidocs/mk/jinja.py#L101

The plugin does not seem to expose this pluggability, but on the other hand the plugin itself is trivial, it's just this 1 file
https://github.com/Neoteroi/mkdocs-plugins/blob/d196ab67594e9cd6adcdda75089bd7020253a08e/neoteroi/mkdocs/oad/__init__.py#L32

[Andre601]

I fixed the jinja thing by having a from openapidocs.mk.jinja import Jinja2DocumentsWriter line at the top.

Tho, right now can it not find the theme module I defined... Is that even the right thing to give? Because looking at essentials-openapi, it seems that Jinja2DocumentsWriter wants a DocumentsWriter: https://github.com/Neoteroi/essentials-openapi/blob/main/openapidocs/mk/jinja.py#L90

(Also, yes I changed my_oad_template to theme in the code.)

[oprypin]

would the path for the template be relative to the mkdocs config file, the hook, or something else?

Because Jinja2DocumentsWriter uses https://jinja.palletsprojects.com/en/3.0.x/api/#jinja2.PackageLoader, the path is relative to Python's import path. That's why if the hook script and the template directory are in the same common directory, it is good to write sys.path.insert(0, os.path.dirname(__file__)) to put the common directory into Python's import path.

[Andre601]

That works. Thank you. Now... time to edit this stuff xD

[oprypin]

Great! And yes your code looks good, it is exactly what I meant

[Andre601]

Looks good!