search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
534 stars 47 forks source link

Add a warning message in case that the theme is not found. #66

Closed codie3611 closed 2 years ago

codie3611 commented 3 years ago

In my setup somehow the "material" theme is not being found and the versioning menu was omitted. It took me quite a while to figure this out. The plugin should not silent exceptions without logging them.

I used the logging code from the mkdocstrings plugin but didn't want to import it directly to avoid a dependency. So many thanks to the authors of that plugin.

jimporter commented 3 years ago

Hm, a warning message could be useful. However, I'm not sure this is the right thing to do, at least not without coordination from mkdocs-material. Currently, mkdocs-material has built-in support for a version selector, and so it doesn't explicitly advertise a mike.themes entrypoint (it would just be a no-op). mkdocs-material uses a different way to activate the version selector: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/.

That said, a warning would help for other themes that truly don't have mike support.

@squidfunk: What do you think about this? Would it make sense for mkdocs-material to add a no-op mike.themes entry point as a way of advertising support for mike? This would probably be similar to my (abandoned) PR https://github.com/squidfunk/mkdocs-material/pull/2059, except without raising an exception.

squidfunk commented 3 years ago

I'm sorry, I don't really understand the problem here. What would the entrypoint solve? Other than that if it's a no-op but helps to disambiguate, we can add it to Material for MkDocs.

jimporter commented 3 years ago

@squidfunk One potential issue with mike is that if someone uses the foo-theme, it might not have any support for the version selector widget (mike isn't smart enough to guess where to put it). In that case, we should emit a warning when building the docs. mike also supports "injecting" a version selector into a theme by making a Python project with the mike.themes entry point (that's what mike does to support the default themes). However, mkdocs-material has its own way of adding the version selector, so it doesn't actually need the mike.themes entry point. That makes it tough for mike to tell whether mkdocs-material will add a version selector. As you say, all this would do is help to disambiguate things for mike.

This will probably take a bit more thought on my end before I merge anything, since the patch as-is doesn't handle the case where a theme has built-in handling for version selectors. Still, so long as it seems reasonable to add some simple logic to mkdocs-material to inform mike that it handles version selectors internally, I can probably come up with a solution here.

squidfunk commented 3 years ago

@jimporter thanks for the heads up! A PR is appreciated which adds the entrypoint if that makes work for you easier.

codie3611 commented 3 years ago

Should I close this PR @jimporter ?

jimporter commented 3 years ago

@tnt-codie I don't have a strong preference. If you do close it though, one of us should file an issue about this for tracking purposes. I'm still considering the options here for how to account for all the various possibilities for various themes, though...

codie3611 commented 2 years ago

@jimporter I will leave it to you how to proceed. Feel free to open and merge this PR if you like.