Added plugin config definition

Author: DSmedley

README.md

@@ -157,6 +157,10 @@ We only use `material-mkdocs` as base styles because Backstage also uses the `Ma
 
 ## Changelog
 
+### 1.5.4
+
+- Added proper plugin config to fix `Unrecognised configuration name` error when any config is provided
+
 ### 1.5.3
 
 - Added support for PyMdown Blocks extensions

setup.py

@@ -28,7 +28,7 @@
 
 setup(
     name="mkdocs-techdocs-core",
-    version="1.5.3",
+    version="1.5.4",
     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,

techdocs_core/core.py

@@ -17,6 +17,8 @@
 import tempfile
 import logging
 import os
+
+from mkdocs.config import Config, config_options
 from mkdocs.plugins import BasePlugin
 from mkdocs.theme import Theme
 from mkdocs.contrib.search import SearchPlugin
@@ -30,7 +32,12 @@
 TECHDOCS_DEFAULT_THEME = "material"
 
 
-class TechDocsCore(BasePlugin):
+class TechDocsCoreConfig(Config):
+    use_material_search = config_options.Type(bool, default=False)
+    use_pymdownx_blocks = config_options.Type(bool, default=False)
+
+
+class TechDocsCore(BasePlugin[TechDocsCoreConfig]):
     def __init__(self):
         # This directory will be removed automatically once the docs are built
         # MkDocs needs a directory for the theme with the `techdocs_metadata.json` file
@@ -76,12 +83,8 @@ def on_config(self, config):
         config["theme"].dirs.append(self.tmp_dir_techdocs_theme.name)
 
         # Plugins
-        use_material_search = config["plugins"]["techdocs-core"].config.get(
-            "use_material_search", False
-        )
-        use_pymdownx_blocks = config["plugins"]["techdocs-core"].config.get(
-            "use_pymdownx_blocks", False
-        )
+        use_material_search = self.config["use_material_search"]
+        use_pymdownx_blocks = self.config["use_pymdownx_blocks"]
         del config["plugins"]["techdocs-core"]
 
         if use_material_search:

techdocs_core/test_core.py

@@ -16,77 +16,77 @@ class DummyTechDocsCorePlugin(plugins.BasePlugin):
     pass
 
 
-class TestTechDocsCoreConfig(unittest.TestCase):
+class TestTechDocsCore(unittest.TestCase):
     def setUp(self):
-        self.techdocscore = TechDocsCore()
         self.plugin_collection = plugins.PluginCollection()
         plugin = DummyTechDocsCorePlugin()
         self.plugin_collection["techdocs-core"] = plugin
-        self.mkdocs_yaml_config = {"plugins": self.plugin_collection}
-        # Note: in reality, config["theme"] is always an instance of Theme
-        self.mkdocs_yaml_config["theme"] = get_default_theme()
+        self.techdocscore = TechDocsCore()
+        self.techdocscore.load_config(
+            {"plugins": self.plugin_collection, "theme": get_default_theme()}
+        )
 
     def test_removes_techdocs_core_plugin_from_config(self):
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
         self.assertTrue("techdocs-core" not in final_config["plugins"])
 
     def test_merge_default_config_and_user_config(self):
-        self.mkdocs_yaml_config["markdown_extension"] = []
-        self.mkdocs_yaml_config["mdx_configs"] = {}
-        self.mkdocs_yaml_config["markdown_extension"].append(["toc"])
-        self.mkdocs_yaml_config["mdx_configs"]["toc"] = {"toc_depth": 3}
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.techdocscore.config["markdown_extension"] = []
+        self.techdocscore.config["mdx_configs"] = {}
+        self.techdocscore.config["markdown_extension"].append(["toc"])
+        self.techdocscore.config["mdx_configs"]["toc"] = {"toc_depth": 3}
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
         self.assertTrue("toc" in final_config["mdx_configs"])
         self.assertTrue("permalink" in final_config["mdx_configs"]["toc"])
         self.assertTrue("toc_depth" in final_config["mdx_configs"]["toc"])
         self.assertTrue("mdx_truly_sane_lists" in final_config["markdown_extensions"])
 
     def test_override_default_config_with_user_config(self):
-        self.mkdocs_yaml_config["markdown_extension"] = []
-        self.mkdocs_yaml_config["mdx_configs"] = {}
-        self.mkdocs_yaml_config["markdown_extension"].append(["toc"])
-        self.mkdocs_yaml_config["mdx_configs"]["toc"] = {"permalink": False}
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.techdocscore.config["markdown_extension"] = []
+        self.techdocscore.config["mdx_configs"] = {}
+        self.techdocscore.config["markdown_extension"].append(["toc"])
+        self.techdocscore.config["mdx_configs"]["toc"] = {"permalink": False}
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
         self.assertTrue("toc" in final_config["mdx_configs"])
         self.assertTrue("permalink" in final_config["mdx_configs"]["toc"])
         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.techdocscore.config["theme"] = Theme(name="mkdocs")
+        self.techdocscore.config["theme"]["features"] = ["navigation.sections"]
+        final_config = self.techdocscore.on_config(self.techdocscore.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.techdocscore.config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
+        self.techdocscore.config["theme"]["features"] = ["navigation.sections"]
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
         self.assertTrue("navigation.sections" in final_config["theme"]["features"])
 
     def test_theme_overrides_techdocs_metadata(self):
-        self.mkdocs_yaml_config["theme"] = Theme(
+        self.techdocscore.config["theme"] = Theme(
             name=TECHDOCS_DEFAULT_THEME, static_templates=["my_static_temples"]
         )
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        final_config = self.techdocscore.on_config(self.techdocscore.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.techdocscore.config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
+        self.techdocscore.config["theme"].dirs.append(custom_theme_dir)
+        final_config = self.techdocscore.on_config(self.techdocscore.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)
+        self.techdocscore.on_config(self.techdocscore.config)
         env = Environment(
             loader=PackageLoader(
                 "techdocs_core", self.techdocscore.tmp_dir_techdocs_theme.name
@@ -103,40 +103,35 @@ def test_template_renders__multiline_value_as_valid_json(self):
         self.assertEqual(config, as_json)
 
     def test_restrict_snippet_base_path(self):
-        self.mkdocs_yaml_config["mdx_configs"] = {
+        self.techdocscore.config["mdx_configs"] = {
             "pymdownx.snippets": {"restrict_base_path": False}
         }
 
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
 
         self.assertEqual(
             final_config["mdx_configs"]["pymdownx.snippets"]["restrict_base_path"],
             True,
         )
 
     def test_material_search(self):
-        self.plugin_collection["techdocs-core"].load_config(
-            {"use_material_search": True}
-        )
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.techdocscore.config["use_material_search"] = True
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
 
         self.assertEqual(
             final_config["plugins"]["search"].__module__,
             "material.plugins.search.plugin",
         )
 
     def test_default_search(self):
-        self.plugin_collection["techdocs-core"].load_config({})
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
         self.assertEqual(
             final_config["plugins"]["search"].__module__, "mkdocs.contrib.search"
         )
 
     def test_pymdownx_blocks(self):
-        self.plugin_collection["techdocs-core"].load_config(
-            {"use_pymdownx_blocks": True}
-        )
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        self.techdocscore.config["use_pymdownx_blocks"] = True
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
 
         self.assertTrue(
             "pymdownx.blocks.admonition" in final_config["markdown_extensions"]
@@ -160,8 +155,7 @@ def test_pymdownx_blocks(self):
         self.assertFalse("pymdownx.tabbed" in final_config["mdx_configs"])
 
     def test_default_pymdownx(self):
-        self.plugin_collection["techdocs-core"].load_config({})
-        final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
+        final_config = self.techdocscore.on_config(self.techdocscore.config)
 
         self.assertFalse(
             "pymdownx.blocks.admonition" in final_config["markdown_extensions"]