chore: add configuration testing

Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>

python/tests/unit/test_config.py

@@ -23,96 +23,228 @@
 
 from __future__ import annotations
 
-from textwrap import dedent
-from typing import TYPE_CHECKING
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
 import pytest
+import yaml
 
-from zensical.config import ConfigurationError, parse_config
+import zensical.config as cfg_module
+from zensical.config import (
+    ConfigurationError,
+    get_builtin_theme_dir,
+    get_theme_dir,
+    parse_config,
+    parse_mkdocs_config,
+)
+from zensical.extensions.autorefs import AutorefsExtension
+from zensical.extensions.glightbox import GlightboxExtension
+from zensical.extensions.macros import MacrosExtension
+from zensical.extensions.mkdocstrings import MkdocstringsExtension
 
 if TYPE_CHECKING:
-    from pathlib import Path
+    from collections.abc import Generator
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _write_toml_config(tmp_path: Path, **project_keys: Any) -> Path:
+    """Write a minimal `zensical.toml` with the given project keys."""
+    docs_dir = project_keys.get("docs_dir", "docs")
+    if docs_dir and not str(docs_dir).startswith(".."):
+        tmp_path.joinpath(docs_dir).mkdir(exist_ok=True)
+
+    lines = ["[project]", 'site_name = "test"']
+    for key, value in project_keys.items():
+        if isinstance(value, bool):
+            formatted = "true" if value else "false"
+        elif isinstance(value, (int, float)):
+            formatted = str(value)
+        else:
+            formatted = f'"{value}"'
+        lines.append(f"{key} = {formatted}")
+
+    config_file = tmp_path / "zensical.toml"
+    config_file.write_text("\n".join(lines) + "\n")
+    return config_file
+
+
+def _minimal_yaml(**extra_keys: object) -> str:
+    """Build a minimal mkdocs.yml YAML string with the required scaffolding."""
+    base: dict[str, Any] = {
+        "site_name": "Test Site",
+        "theme": {"name": "material"},
+        "extra": {},
+        "plugins": [],
+        "mdx_configs": {},
+    }
+    base.update(extra_keys)
+    return yaml.dump(base)
+
+
+def _write_mkdocs_config(tmp_path: Path, yaml_str: str) -> Path:
+    """Create the `docs` directory and write `mkdocs.yml` content."""
+    tmp_path.joinpath("docs").mkdir()
+    config_file = tmp_path / "mkdocs.yml"
+    config_file.write_text(yaml_str)
+    return config_file
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _reset_config() -> Generator[None, None, None]:
+    """Reset the global _CONFIG before and after each test."""
+    cfg_module._CONFIG = None
+    yield
+    cfg_module._CONFIG = None
 
 
 def test_site_dir_cant_be_empty(tmp_path: Path) -> None:
-    tmp_path.joinpath("docs").mkdir()
-    config_file = tmp_path / "zensical.toml"
-    config_file.write_text(
-        dedent("""
-            [project]
-            site_name = "test"
-            site_dir = ""
-            """)
-    )
+    config_file = _write_toml_config(tmp_path, site_dir="")
     with pytest.raises(ConfigurationError, match="empty"):
         parse_config(str(config_file))
 
 
 def test_site_dir_cant_go_up(tmp_path: Path) -> None:
-    tmp_path.joinpath("docs").mkdir()
-    config_file = tmp_path / "zensical.toml"
-    config_file.write_text(
-        dedent("""
-            [project]
-            site_name = "test"
-            site_dir = "../site"
-            """)
-    )
+    config_file = _write_toml_config(tmp_path, site_dir="../site")
     with pytest.raises(ConfigurationError, match="within"):
         parse_config(str(config_file))
 
 
 def test_docs_dir_cant_be_empty(tmp_path: Path) -> None:
-    tmp_path.joinpath("docs").mkdir()
-    config_file = tmp_path / "zensical.toml"
-    config_file.write_text(
-        dedent("""
-            [project]
-            site_name = "test"
-            docs_dir = ""
-            """)
-    )
+    config_file = _write_toml_config(tmp_path, docs_dir="")
     with pytest.raises(ConfigurationError, match="empty"):
         parse_config(str(config_file))
 
 
 def test_docs_dir_cant_go_up(tmp_path: Path) -> None:
-    tmp_path.joinpath("docs").mkdir()
-    config_file = tmp_path / "zensical.toml"
-    config_file.write_text(
-        dedent("""
-            [project]
-            site_name = "test"
-            docs_dir = "../docs"
-            """)
-    )
+    config_file = _write_toml_config(tmp_path, docs_dir="../docs")
     with pytest.raises(ConfigurationError, match="within"):
         parse_config(str(config_file))
 
 
 def test_docs_dir_must_exist(tmp_path: Path) -> None:
-    config_file = tmp_path / "zensical.toml"
-    config_file.write_text(
-        dedent("""
-            [project]
-            site_name = "test"
-            docs_dir = "docs"
-            """)
-    )
+    config_file = _write_toml_config(tmp_path, docs_dir="docs")
+    # Remove the auto-created docs directory to trigger the existence check.
+    tmp_path.joinpath("docs").rmdir()
     with pytest.raises(ConfigurationError, match="does not exist"):
         parse_config(str(config_file))
 
 
 def test_site_dir_docs_dir_cant_be_equal(tmp_path: Path) -> None:
-    tmp_path.joinpath("docs").mkdir()
-    config_file = tmp_path / "zensical.toml"
-    config_file.write_text(
-        dedent("""
-            [project]
-            site_name = "test"
-            site_dir = "same"
-            docs_dir = "same"
-            """)
-    )
+    config_file = _write_toml_config(tmp_path, site_dir="same", docs_dir="same")
     with pytest.raises(ConfigurationError, match="must be different"):
         parse_config(str(config_file))
+
+
+# ---------------------------------------------------------------------------
+# Plugins to Markdown extensions
+# ---------------------------------------------------------------------------
+
+
+class TestPluginShimming:
+    """Test that MkDocs plugin entries are shimmed into Markdown extensions."""
+
+    def _parse_yaml(
+        self, tmp_path: Path, **yaml_overrides: object
+    ) -> dict[str, Any]:
+        """Write a minimal mkdocs.yml with overrides and return config."""
+        yaml_str = _minimal_yaml(**yaml_overrides)
+        config_file = _write_mkdocs_config(tmp_path, yaml_str)
+        parse_mkdocs_config(str(config_file))
+        config = cfg_module._CONFIG
+        assert config is not None
+        return config
+
+    def test_plugins_as_yaml_list(self, tmp_path: Path) -> None:
+        config = self._parse_yaml(tmp_path, plugins=["glightbox"])
+        assert GlightboxExtension.name in config["markdown_extensions"]
+
+    def test_plugins_as_yaml_dict(self, tmp_path: Path) -> None:
+        config = self._parse_yaml(tmp_path, plugins={"glightbox": {}})
+        assert GlightboxExtension.name in config["markdown_extensions"]
+
+    def test_glightbox_adds_extension_and_forwards_config(
+        self, tmp_path: Path
+    ) -> None:
+        config = self._parse_yaml(
+            tmp_path, plugins={"glightbox": {"loop": True}}
+        )
+        assert GlightboxExtension.name in config["markdown_extensions"]
+        assert config["mdx_configs"][GlightboxExtension.name] == {"loop": True}
+
+    def test_macros_plugin_shimmed(self, tmp_path: Path) -> None:
+        config = self._parse_yaml(tmp_path, plugins={"macros": {}})
+        assert MacrosExtension.name in config["markdown_extensions"]
+
+    def test_autorefs_standalone(self, tmp_path: Path) -> None:
+        config = self._parse_yaml(tmp_path, plugins={"autorefs": {}})
+        assert AutorefsExtension.name in config["markdown_extensions"]
+
+    def test_autorefs_disabled_not_added(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        monkeypatch.setattr("zensical.config.find_spec", lambda _name: True)
+        config = self._parse_yaml(
+            tmp_path,
+            plugins={
+                "autorefs": {"enabled": False},
+                "mkdocstrings": {"enabled": True},
+            },
+        )
+        assert AutorefsExtension.name not in config["markdown_extensions"]
+
+    def test_mkdocstrings_disabled_neither_added(self, tmp_path: Path) -> None:
+        config = self._parse_yaml(
+            tmp_path, plugins={"mkdocstrings": {"enabled": False}}
+        )
+        assert AutorefsExtension.name not in config["markdown_extensions"]
+        assert MkdocstringsExtension.name not in config["markdown_extensions"]
+
+    def test_mkdocstrings_enabled_autorefs_also_added(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        monkeypatch.setattr("zensical.config.find_spec", lambda _name: True)
+        config = self._parse_yaml(tmp_path, plugins={"mkdocstrings": {}})
+        assert AutorefsExtension.name in config["markdown_extensions"]
+        assert MkdocstringsExtension.name in config["markdown_extensions"]
+
+    def test_mkdocstrings_not_installed_raises(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
+    ) -> None:
+        monkeypatch.setattr("zensical.config.find_spec", lambda _name: None)
+        yaml_str = _minimal_yaml(plugins={"mkdocstrings": {}})
+        config_file = _write_mkdocs_config(tmp_path, yaml_str)
+        with pytest.raises(ConfigurationError):
+            parse_mkdocs_config(str(config_file))
+
+
+# ---------------------------------------------------------------------------
+# Getting theme information
+# ---------------------------------------------------------------------------
+
+
+class TestGetThemeDir:
+    """Test theme directory resolution."""
+
+    def test_builtin_theme_dir_exists(self) -> None:
+        assert Path(get_builtin_theme_dir()).exists()
+
+    def test_get_theme_dir_material(self) -> None:
+        assert get_theme_dir("material") == get_builtin_theme_dir()
+
+    def test_get_theme_dir_zensical(self) -> None:
+        assert get_theme_dir("zensical") == get_builtin_theme_dir()
+
+    def test_get_theme_dir_unknown_raises(self) -> None:
+        with pytest.raises(ConfigurationError):
+            get_theme_dir("definitely-not-a-real-theme-xyzzy")