Merge pull request #67 from aladjadj/fix_theme_override

Simplify how the theme is override

README.md

@@ -132,6 +132,10 @@ We only use `material-mkdocs` as base styles because Backstage also uses the `Ma
 
 ## Changelog
 
+### 1.1.2
+
+- Simplify theme code to update only the attribute necessary by backstage.
+
 ### 1.1.1
 
 - Fix run-time `AttributeError: 'Theme' object has no attribute 'copy'`

setup.py

@@ -27,7 +27,7 @@
 
 setup(
     name="mkdocs-techdocs-core",
-    version="1.1.1",
+    version="1.1.2",
     description="The core MkDocs plugin used by Backstage's TechDocs as a wrapper around "
     "multiple MkDocs plugins and Python Markdown extensions",
     long_description=long_description,

src/core.py

@@ -15,13 +15,20 @@
 """
 
 import tempfile
+import logging
 import os
 from mkdocs.plugins import BasePlugin
 from mkdocs.theme import Theme
+from mkdocs.utils import warning_filter
 from mkdocs.contrib.search import SearchPlugin
 from mkdocs_monorepo_plugin.plugin import MonorepoPlugin
 from pymdownx.emoji import to_svg
 
+log = logging.getLogger(__name__)
+log.addFilter(warning_filter)
+
+TECHDOCS_DEFAULT_THEME = "material"
+
 
 class TechDocsCore(BasePlugin):
     def __init__(self):
@@ -44,25 +51,16 @@ def on_config(self, config):
             mdx_configs_override = config["mdx_configs"].copy()
 
         # Theme
-        theme_override = {}
-        if "theme" in config:
-            theme_override = config["theme"]
-
-        config["theme"] = Theme(
-            name="material",
-            static_templates=[
-                "techdocs_metadata.json",
-            ],
-        )
-        config["theme"].dirs.append(self.tmp_dir_techdocs_theme.name)
+        if config["theme"].name != TECHDOCS_DEFAULT_THEME:
+            config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
+        elif config["theme"].name == TECHDOCS_DEFAULT_THEME:
+            log.info(
+                "[mkdocs-techdocs-core] Overridden '%s' theme settings in use",
+                TECHDOCS_DEFAULT_THEME,
+            )
 
-        for key in theme_override:
-            if key not in config["theme"]:
-                config["theme"][key] = theme_override[key]
-            elif key in ["static_templates", "dir"]:
-                default_config = config["theme"][key]
-                override_config = theme_override[key]
-                config["theme"][key] = [*default_config, *override_config]
+        config["theme"].static_templates.update({"techdocs_metadata.json"})
+        config["theme"].dirs.append(self.tmp_dir_techdocs_theme.name)
 
         # Plugins
         del config["plugins"]["techdocs-core"]

src/test_core.py

@@ -1,7 +1,7 @@
 import unittest
 import mkdocs.plugins as plugins
 from mkdocs.theme import Theme
-from .core import TechDocsCore
+from .core import TechDocsCore, TECHDOCS_DEFAULT_THEME
 from jinja2 import Environment, PackageLoader, select_autoescape
 import json
 
@@ -51,6 +51,39 @@ def test_override_default_config_with_user_config(self):
         self.assertFalse(final_config["mdx_configs"]["toc"]["permalink"])
         self.assertTrue("mdx_truly_sane_lists" in final_config["markdown_extensions"])
 
+    def test_theme_overrides_removed_when_name_is_not_material(self):
+        ## we want to force the theme mkdocs to this test
+        self.mkdocs_yaml_config["theme"] = Theme(name="mkdocs")
+        self.mkdocs_yaml_config["theme"]["features"] = ["navigation.sections"]
+        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.assertFalse("navigation.sections" in final_config["theme"]["features"])
+
+    def test_theme_overrides_when_name_is_material(self):
+        self.mkdocs_yaml_config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
+        self.mkdocs_yaml_config["theme"]["features"] = ["navigation.sections"]
+        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.assertTrue("navigation.sections" in final_config["theme"]["features"])
+
+    def test_theme_overrides_techdocs_metadata(self):
+        self.mkdocs_yaml_config["theme"] = Theme(
+            name=TECHDOCS_DEFAULT_THEME, static_templates=["my_static_temples"]
+        )
+        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.assertTrue("my_static_temples" in final_config["theme"].static_templates)
+        self.assertTrue(
+            "techdocs_metadata.json" in final_config["theme"].static_templates
+        )
+
+    def test_theme_overrides_dirs(self):
+        custom_theme_dir = "/tmp/my_custom_theme_dir"
+        self.mkdocs_yaml_config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
+        self.mkdocs_yaml_config["theme"].dirs.append(custom_theme_dir)
+        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.assertTrue(custom_theme_dir in final_config["theme"].dirs)
+        self.assertTrue(
+            self.techdocscore.tmp_dir_techdocs_theme.name in final_config["theme"].dirs
+        )
+
     def test_template_renders__multiline_value_as_valid_json(self):
         self.techdocscore.on_config(self.mkdocs_yaml_config)
         env = Environment(