mirror of
https://github.com/zensical/zensical.git
synced 2026-09-28 17:25:43 +00:00
513 lines
19 KiB
Python
Vendored
513 lines
19 KiB
Python
Vendored
# Copyright (c) 2025-2026 Zensical and contributors
|
|
|
|
# SPDX-License-Identifier: MIT
|
|
# All contributions are certified under the DCO
|
|
|
|
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
# of this software and associated documentation files (the "Software"), to
|
|
# deal in the Software without restriction, including without limitation the
|
|
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
|
# sell copies of the Software, and to permit persons to whom the Software is
|
|
# furnished to do so, subject to the following conditions:
|
|
|
|
# The above copyright notice and this permission notice shall be included in
|
|
# all copies or substantial portions of the Software.
|
|
|
|
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
|
|
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
|
# IN THE SOFTWARE.
|
|
|
|
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
from typing import TYPE_CHECKING, Any
|
|
|
|
import pytest
|
|
import yaml
|
|
|
|
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 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:
|
|
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:
|
|
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:
|
|
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:
|
|
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 = _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:
|
|
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"]
|
|
|
|
@pytest.mark.parametrize(
|
|
"entry", ["material/meta", {"material/meta": None}]
|
|
)
|
|
def test_material_meta_presence_enables_defaults(
|
|
self, tmp_path: Path, entry: object
|
|
) -> None:
|
|
config = self._parse_yaml(tmp_path, plugins=[entry])
|
|
assert config["plugins"]["meta"]["config"] == {
|
|
"enabled": True,
|
|
"meta_file": ".meta.yml",
|
|
}
|
|
|
|
def test_material_meta_plugin_is_normalized(self, tmp_path: Path) -> None:
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
plugins={"material/meta": {"meta_file": "defaults.yml"}},
|
|
)
|
|
assert "material/meta" not in config["plugins"]
|
|
assert config["plugins"]["meta"]["config"] == {
|
|
"enabled": True,
|
|
"meta_file": "defaults.yml",
|
|
}
|
|
assert config["plugins_hash"] == cfg_module._hash(config["plugins"])
|
|
|
|
@pytest.mark.parametrize(
|
|
"name",
|
|
[
|
|
"material/meta",
|
|
"redirects",
|
|
"minify",
|
|
"literate-nav",
|
|
"awesome-nav",
|
|
],
|
|
)
|
|
def test_native_plugin_configuration_must_be_a_mapping(
|
|
self, tmp_path: Path, name: str
|
|
) -> None:
|
|
with pytest.raises(
|
|
cfg_module.ConfigurationError,
|
|
match=rf"{name} configuration must be a mapping",
|
|
):
|
|
self._parse_yaml(tmp_path, plugins={name: []})
|
|
|
|
def test_redirects_plugin_is_normalized(self, tmp_path: Path) -> None:
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
plugins={"redirects": {"redirect_maps": {"old.md": "new.md"}}},
|
|
)
|
|
assert config["plugins"]["redirects"]["config"] == {
|
|
"enabled": True,
|
|
"redirect_maps": {"old.md": "new.md"},
|
|
}
|
|
|
|
def test_redirects_plugin_is_disabled_by_default(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
config = self._parse_yaml(tmp_path, plugins=[])
|
|
assert config["plugins"]["redirects"]["config"] == {
|
|
"enabled": False,
|
|
"redirect_maps": {},
|
|
}
|
|
|
|
@pytest.mark.parametrize("entry", ["literate-nav", {"literate-nav": None}])
|
|
def test_literate_nav_presence_enables_defaults(
|
|
self, tmp_path: Path, entry: object
|
|
) -> None:
|
|
config = self._parse_yaml(tmp_path, plugins=[entry])
|
|
plugin = config["plugins"]["literate_nav"]["config"]
|
|
assert plugin == {
|
|
"enabled": True,
|
|
"nav_file": "SUMMARY.md",
|
|
"implicit_index": False,
|
|
"tab_length": 4,
|
|
"markdown_extensions": [],
|
|
"mdx_configs": {},
|
|
}
|
|
|
|
def test_literate_nav_is_disabled_when_absent(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
config = self._parse_yaml(tmp_path, plugins=[])
|
|
assert config["plugins"]["literate_nav"]["config"]["enabled"] is False
|
|
|
|
def test_literate_nav_normalizes_local_markdown_extensions(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
plugins={
|
|
"literate-nav": {
|
|
"nav_file": "NAV.md",
|
|
"implicit_index": True,
|
|
"tab_length": 2,
|
|
"markdown_extensions": [
|
|
"abbr",
|
|
{"toc": {"permalink": False}},
|
|
],
|
|
}
|
|
},
|
|
)
|
|
plugin = config["plugins"]["literate_nav"]["config"]
|
|
assert plugin["nav_file"] == "NAV.md"
|
|
assert plugin["implicit_index"] is True
|
|
assert plugin["tab_length"] == 2
|
|
assert plugin["markdown_extensions"] == ["abbr", "toc"]
|
|
assert plugin["mdx_configs"] == {
|
|
"abbr": {},
|
|
"toc": {"permalink": False},
|
|
}
|
|
|
|
@pytest.mark.parametrize("entry", ["awesome-nav", {"awesome-nav": None}])
|
|
def test_awesome_nav_presence_enables_defaults(
|
|
self, tmp_path: Path, entry: object
|
|
) -> None:
|
|
config = self._parse_yaml(tmp_path, plugins=[entry])
|
|
assert config["plugins"]["awesome_nav"]["config"] == {
|
|
"enabled": True,
|
|
"filename": ".nav.yml",
|
|
"logs": {
|
|
"nav_override": None,
|
|
"root_title": None,
|
|
"root_hide": None,
|
|
"no_matches": None,
|
|
},
|
|
}
|
|
|
|
def test_awesome_nav_is_disabled_when_absent(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
plugin = self._parse_yaml(tmp_path, plugins=[])["plugins"]
|
|
assert plugin["awesome_nav"]["config"]["enabled"] is False
|
|
|
|
def test_awesome_nav_normalizes_filename_and_logs(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
plugins={
|
|
"awesome-nav": {
|
|
"filename": "awesome.yml",
|
|
"logs": {"no_matches": "error"},
|
|
}
|
|
},
|
|
)
|
|
plugin = config["plugins"]["awesome_nav"]["config"]
|
|
assert plugin["filename"] == "awesome.yml"
|
|
assert plugin["logs"]["no_matches"] == "error"
|
|
assert plugin["logs"]["root_title"] is None
|
|
|
|
@pytest.mark.parametrize(
|
|
("plugin", "message"),
|
|
[
|
|
({"unknown": True}, "unknown awesome-nav option"),
|
|
({"filename": 42}, "filename must be a string"),
|
|
({"filename": ""}, "filename must not be empty"),
|
|
({"logs": "warning"}, "logs must be a mapping"),
|
|
({"logs": {"unknown": "info"}}, "unknown awesome-nav log"),
|
|
(
|
|
{"logs": {"no_matches": "debug"}},
|
|
"must be info, warning or error",
|
|
),
|
|
],
|
|
)
|
|
def test_awesome_nav_rejects_invalid_plugin_options(
|
|
self, tmp_path: Path, plugin: object, message: str
|
|
) -> None:
|
|
with pytest.raises(cfg_module.ConfigurationError, match=message):
|
|
self._parse_yaml(tmp_path, plugins={"awesome-nav": plugin})
|
|
|
|
def test_minify_plugin_is_normalized(self, tmp_path: Path) -> None:
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
plugins={
|
|
"minify": {
|
|
"minify_html": True,
|
|
"minify_inline_js": True,
|
|
"js_files": "assets/app.js",
|
|
"css_files": ["assets/app.css"],
|
|
"htmlmin_opts": {
|
|
"remove_comments": True,
|
|
"pre_tags": ["pre", "textarea", "code"],
|
|
},
|
|
}
|
|
},
|
|
)
|
|
assert config["plugins"]["minify"]["config"] == {
|
|
"enabled": True,
|
|
"minify_html": True,
|
|
"minify_js": False,
|
|
"minify_css": False,
|
|
"minify_inline_js": True,
|
|
"minify_inline_css": False,
|
|
"js_files": ["assets/app.js"],
|
|
"css_files": ["assets/app.css"],
|
|
"htmlmin_opts": {
|
|
"remove_comments": True,
|
|
"remove_empty_space": False,
|
|
"remove_all_empty_space": False,
|
|
"reduce_empty_attributes": True,
|
|
"reduce_boolean_attributes": False,
|
|
"remove_optional_attribute_quotes": True,
|
|
"convert_charrefs": True,
|
|
"keep_pre": False,
|
|
"pre_tags": ["pre", "textarea", "code"],
|
|
"pre_attr": "pre",
|
|
},
|
|
"cache_safe": False,
|
|
}
|
|
|
|
def test_minify_plugin_is_disabled_by_default(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
config = self._parse_yaml(tmp_path, plugins=[])
|
|
plugin = config["plugins"]["minify"]["config"]
|
|
assert plugin["enabled"] is False
|
|
assert plugin["minify_html"] is False
|
|
assert plugin["htmlmin_opts"]["pre_tags"] == ["pre", "textarea"]
|
|
|
|
def test_tags_plugin_instances_are_preserved_for_rust_normalization(
|
|
self, tmp_path: Path
|
|
) -> None:
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
plugins=[
|
|
{"tags": {"listings_directive": "$tags"}},
|
|
{
|
|
"material/tags/private": {
|
|
"filters": {"include": ["private/**"]},
|
|
"tags_name_property": "labels",
|
|
}
|
|
},
|
|
],
|
|
)
|
|
instances = config["plugins"]["tags"]["config"]
|
|
assert [instance["name"] for instance in instances] == [
|
|
"tags",
|
|
"material/tags/private",
|
|
]
|
|
assert instances[0]["config"]["listings_directive"] == "$tags"
|
|
assert instances[1]["config"]["filters"] == {
|
|
"include": ["private/**"]
|
|
}
|
|
assert instances[1]["config"]["tags_name_property"] == "labels"
|
|
assert "tags_slugify" not in instances[0]["config"]
|
|
|
|
def test_mike_plugin_defaults_with_versioned_build(
|
|
self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
|
|
) -> None:
|
|
monkeypatch.setenv("MIKE_DOCS_VERSION", "0.3")
|
|
config = self._parse_yaml(
|
|
tmp_path,
|
|
site_url="https://example.com",
|
|
plugins=["mike"],
|
|
)
|
|
assert config["site_url"] == "https://example.com/0.3"
|
|
assert config["plugins"]["mike"]["config"] == {
|
|
"alias_type": "symlink",
|
|
"redirect_template": None,
|
|
"deploy_prefix": "",
|
|
"canonical_version": None,
|
|
}
|
|
|
|
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")
|