Support loading existing mkdocs themes

Simply support the mkdocs.themes entrypoints but give preference to our entrypoints.

Also, populate the mkdocs_version field for themes but with our project name prefix, to distinguish them if the theme renders this value.

Author: oprypin

docs/dev-guide/themes.md

@@ -315,7 +315,7 @@ this can be used directly by prepending it to a local relative URL, it is best
 to use the [url](#url) template filter, which is smarter about how it applies
 `base_url`.
 
-#### mkdocs_version
+#### properdocs_version
 
 Contains the current ProperDocs version.
 

properdocs/commands/build.py

@@ -51,7 +51,8 @@ def get_context(
         base_url=base_url,
         extra_css=extra_css,
         extra_javascript=extra_javascript,
-        mkdocs_version=properdocs.__version__,
+        properdocs_version=properdocs.__version__,
+        mkdocs_version=f"ProperDocs {properdocs.__version__}",
         build_date_utc=utils.get_build_datetime(),
         config=config,
         page=page,

properdocs/plugins.py

@@ -49,7 +49,7 @@ def get_plugins() -> dict[str, EntryPoint]:
 
     for prefix in pluginmaps:
         for plugin in entry_points(group=f'{prefix}.plugins'):
-            if plugin.value.startswith('mkdocs.'):
+            if getattr(plugin, 'value', '').startswith('mkdocs.'):
                 continue
             # Allow third-party plugins to override core plugins
             if plugin.name in pluginmaps[prefix] and plugin.value.startswith(f"{prefix}.contrib."):

properdocs/tests/config/config_options_tests.py

@@ -1939,6 +1939,7 @@ class ThemePlugin2(BasePlugin[_FakePluginConfig]):
 class FakeEntryPoint:
     def __init__(self, name, cls):
         self.name = name
+        self.value = 'properdocs'
         self.cls = cls
 
     def load(self):

properdocs/utils/__init__.py

@@ -262,10 +262,21 @@ def get_theme_dir(name: str) -> str:
 @functools.lru_cache(maxsize=None)
 def get_themes() -> dict[str, EntryPoint]:
     """Return a dict of all installed themes as {name: EntryPoint}."""
-    themes: dict[str, EntryPoint] = {}
-    eps: dict[EntryPoint, None] = dict.fromkeys(entry_points(group='properdocs.themes'))
-    builtins = {ep.name for ep in eps if ep.dist is not None and ep.dist.name == 'properdocs'}
+    # Ordered set of preferred entry points.
+    eps: dict[EntryPoint, None] = {}
+    builtins: set[str] = set()
+
+    for ep in entry_points(group='mkdocs.themes'):
+        if ep.dist is not None and ep.dist.name != 'mkdocs':
+            eps[ep] = None
+    # These will get preference because they are later in the sequence:
+    for ep in entry_points(group='properdocs.themes'):
+        if ep.dist is not None:
+            eps[ep] = None
+            if ep.dist.name == 'properdocs':
+                builtins.add(ep.name)
 
+    themes: dict[str, EntryPoint] = {}
     for theme in eps:
         assert theme.dist is not None
 

properdocs/utils/templates.py

@@ -28,6 +28,7 @@ class TemplateContext(TypedDict):
     base_url: str
     extra_css: Sequence[str]  # Do not use, prefer `config.extra_css`.
     extra_javascript: Sequence[str]  # Do not use, prefer `config.extra_javascript`.
+    properdocs_version: str
     mkdocs_version: str
     build_date_utc: datetime.datetime
     config: ProperDocsConfig