Open carlocastoldi opened 1 month ago
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?
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.
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
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.
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 :)
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...
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?
from what I understand
fallback_theme
should be anBaseHandler
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)?