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
+#### montydocs_version
 
 Contains the current MontyDocs version.
 

montydocs/commands/build.py

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

montydocs/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='montydocs.themes'))
-    builtins = {ep.name for ep in eps if ep.dist is not None and ep.dist.name == 'montydocs'}
+    # 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='montydocs.themes'):
+        if ep.dist is not None:
+            eps[ep] = None
+            if ep.dist.name == 'montydocs':
+                builtins.add(ep.name)
 
+    themes: dict[str, EntryPoint] = {}
     for theme in eps:
         assert theme.dist is not None
 

montydocs/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`.
+    montydocs_version: str
     mkdocs_version: str
     build_date_utc: datetime.datetime
     config: MontyDocsConfig