fallback_theme option is not overridable

[carlocastoldi]

from what I understand fallback_theme should be an BaseHandler attribute used to fallback to a theme when the default global mkdocs theme is unavailable in mkdocstrings.

Should this option be settable from mkdocs.yml? If so, i am afraid it does not work. If it shouldn't, is there a reason why python should not fallback to readthedocs theme (or anything else)?

[pawamoy]

Good questions!

The initial intent for fallback_theme was to allow handler developers to write generic templates once (within a specific theme folder) and let other themes use them. It's kind of an implicit "common template" internal feature.

It was never meant to be exposed to users (and is not), and wouldn't even work as you expect it if it was.

Nowadays I'm thinking about getting rid of the fallback mechanism in favor of fully explicit templates: each theme folder should implement all necessary templates, even if that means duplication/redundancy with other theme folders.

Does it answer your questions?

[pawamoy]

As for why falling back to material in mkdocstrings-python: no particular reason, that's just our preferred theme and the one we support best.

[carlocastoldi]

Just to give a bit of context of why i'm interested in this: I'm developing a very basic plugin to allow using different themes on a selected set of pages. I was particularly interested in having API reference pages different from the rest. However I've noticed that mkdocstrings deduces which theme to use from the config file and offers no way to change this behaviour to my knowledge.

For this reason I thought of this workaround: define a CombinedEvent on on_config, set the config theme's to an invalid value, let mkdocstring take this value, revert the change to to the default theme. My assumption was that the user could then change mkdocstrings theme using fallback_theme config parameter. I was wrong, as you explained!

Nowadays I'm thinking about getting rid of the fallback mechanism in favor of fully explicit templates: each theme folder should implement all necessary templates, even if that means duplication/redundancy with other theme folders.

Oh interesting. Would that mean that each theme would be responsible of supporting mkdocstring by itself?

Does it answer your questions?

pretty much, yes! Thanks a lot for your speedy reply

[pawamoy]

Would that mean that each theme would be responsible of supporting mkdocstring by itself?

Not at all. That rather mean that in the future we would have one package per handler and per theme, for example mkdocstrings-python-material, mkdocstrings-python-readthedocs, etc. But in the meantime it just means we would stop sharing templates between themes in handlers.

[pawamoy]

I was particularly interested in having API reference pages different from the rest.

You know you can override templates right? Besides, applying for example the RTD templates in a Material site wouldn't make much sense and would yield bad results. It's probably a better idea to override and customize mkdocstrings templates. I'm on mobile so I'll let you check the docs :)

[carlocastoldi]

Oh yes, i know about that! I actually used them and I was happy with the results

However when using my multi-theme plugin with RTD global theme and Material theme for API reference pages, mkdocstring would apply RTD template. Trying to override RTD templates to be like Material didn't seem to work for me (e.g. it couldn't show the symbol type in headings). I'm sure I'm missing something, I just don't know what, tho...

[pawamoy]

If you can provide a reproducible example of the issue you're facing when overriding templates, I can look into it :slightly_smiling_face: The code symbols are a mix of HTML and CSS, maybe you forgot to define the CSS?

[carlocastoldi]

I am sorry for my late reply! It is hard for me to define a small reproducible example. In the end i think my request is very unique and, probably, only possible when using my multi-theme plugin.

For now I setup an ugly workaround: if mkdocstrings is an active plugin, I change the configuration theme to be the one used for mkdocstrings pages, then—once all plugins run on_config()—i switch back to use the main theme (the one used for the rest of the pages that are not API reference).

This has the drawback that if, for some reason, other plugins are using the information about the theme's name in the config file, then it may given unexpected results. That's why initially I was wondering whether i could manually tell mkdocstrings which theme to forcibly use.

[pawamoy]

No worries, thanks for the reply.

I'm going to close this since I don't think there's anything actionable, butt if you have specific requests, don't hesitate to open new issues :slightly_smiling_face: