zensical 0.0.7__cp310-abi3-macosx_10_12_x86_64.whl → 0.0.12__cp310-abi3-macosx_10_12_x86_64.whl

zensical/__init__.py

@@ -21,8 +21,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-from .zensical import *
+from zensical.zensical import *  # noqa: F403
 
-__doc__ = zensical.__doc__
-if hasattr(zensical, "__all__"):
-    __all__ = zensical.__all__
+__doc__ = zensical.__doc__  # type: ignore[name-defined]  # noqa: F405
+if hasattr(zensical, "__all__"):  # type: ignore[name-defined]  # noqa: F405
+    __all__ = zensical.__all__  # type: ignore[name-defined]  # noqa: F405

zensical/bootstrap/.github/workflows/docs.yml

@@ -26,3 +26,4 @@ jobs:
         with:
           path: site
       - uses: actions/deploy-pages@v4
+        id: deployment

zensical/bootstrap/zensical.toml

@@ -57,7 +57,7 @@ Copyright © 2025 The authors
 #
 # Read more: https://zensical.org/docs/customization/#additional-css
 #
-#extra_css = ["assets/stylesheets/extra.css"]
+#extra_css = ["stylesheets/extra.css"]
 
 # With the `extra_javascript` option you can add your own JavaScript to your
 # project to customize the behavior according to your needs.
@@ -65,7 +65,7 @@ Copyright © 2025 The authors
 # The path provided should be relative to the "docs_dir".
 #
 # Read more: https://zensical.org/docs/customization/#additional-javascript
-#extra_javascript = ["assets/javascript/extra.js"]
+#extra_javascript = ["javascripts/extra.js"]
 
 # ----------------------------------------------------------------------------
 # Section for configuring theme options
@@ -93,7 +93,7 @@ Copyright © 2025 The authors
 # - https://zensical.org/docs/setup/logo-and-icons/#favicon
 # - https://developer.mozilla.org/en-US/docs/Glossary/Favicon
 #
-#favicon = "assets/images/favicon.png"
+#favicon = "images/favicon.png"
 
 # Zensical supports more than 60 different languages. This means that the
 # labels and tooltips that Zensical's templates produce are translated.

zensical/config.py

@@ -23,24 +23,26 @@
 
 from __future__ import annotations
 
+import hashlib
 import importlib
 import os
-import yaml
-
-try:
-    import tomllib
-except ModuleNotFoundError:
-    import tomli as tomllib  # type: ignore
+import pickle
+from typing import IO, Any
+from urllib.parse import urlparse
 
+import yaml
 from click import ClickException
 from deepmerge import always_merger
-from functools import partial
-from typing import Any, IO
 from yaml import BaseLoader, Loader, YAMLError
 from yaml.constructor import ConstructorError
-from urllib.parse import urlparse
 
-from .extensions.emoji import to_svg, twemoji
+from zensical.extensions.emoji import to_svg, twemoji
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib  # type: ignore[no-redef]
+
 
 # ----------------------------------------------------------------------------
 # Globals
@@ -63,9 +65,7 @@ side, and use it directly when needed. It's a hack but will do for now.
 
 
 class ConfigurationError(ClickException):
-    """
-    Configuration resolution or validation failed.
-    """
+    """Configuration resolution or validation failed."""
 
 
 # ----------------------------------------------------------------------------
@@ -74,20 +74,17 @@ class ConfigurationError(ClickException):
 
 
 def parse_config(path: str) -> dict:
-    """
-    Parse configuration file.
-    """
-    if path.endswith("zensical.toml"):
+    """Parse configuration file."""
+    # Decide by extension; no need to convert to Path
+    _, ext = os.path.splitext(path)
+    if ext.lower() == ".toml":
         return parse_zensical_config(path)
-    else:
-        return parse_mkdocs_config(path)
+    return parse_mkdocs_config(path)
 
 
 def parse_zensical_config(path: str) -> dict:
-    """
-    Parse zensical.toml configuration file.
-    """
-    global _CONFIG
+    """Parse zensical.toml configuration file."""
+    global _CONFIG  # noqa: PLW0603
     with open(path, "rb") as f:
         config = tomllib.load(f)
     if "project" in config:
@@ -99,11 +96,9 @@ def parse_zensical_config(path: str) -> dict:
 
 
 def parse_mkdocs_config(path: str) -> dict:
-    """
-    Parse mkdocs.yml configuration file.
-    """
-    global _CONFIG
-    with open(path, "r") as f:
+    """Parse mkdocs.yml configuration file."""
+    global _CONFIG  # noqa: PLW0603
+    with open(path, encoding="utf-8") as f:
         config = _yaml_load(f)
 
     # Apply defaults and return parsed configuration
@@ -111,17 +106,20 @@ def parse_mkdocs_config(path: str) -> dict:
     return _CONFIG
 
 
+def get_config() -> dict:
+    """Return configuration."""
+    # We assume this function is only called after populating `_CONFIG`.
+    return _CONFIG  # type: ignore[return-value]
+
+
 def get_theme_dir() -> str:
-    """
-    Return the theme directory.
-    """
+    """Return the theme directory."""
     path = os.path.dirname(os.path.abspath(__file__))
     return os.path.join(path, "templates")
 
 
 def _apply_defaults(config: dict, path: str) -> dict:
-    """
-    Apply default settings in configuration.
+    """Apply default settings in configuration.
 
     Note that this is loosely based on the defaults that MkDocs sets in its own
     configuration system, which we won't port for compatibility right now, as
@@ -136,12 +134,12 @@ def _apply_defaults(config: dict, path: str) -> dict:
 
     # Set site directory
     set_default(config, "site_dir", "site", str)
-    if ".." in config.get("site_dir"):
+    if ".." in config.get("site_dir", ""):
         raise ConfigurationError("site_dir must not contain '..'")
 
     # Set docs directory
     set_default(config, "docs_dir", "docs", str)
-    if ".." in config.get("docs_dir"):
+    if ".." in config.get("docs_dir", ""):
         raise ConfigurationError("docs_dir must not contain '..'")
 
     # Set defaults for core settings
@@ -159,21 +157,26 @@ def _apply_defaults(config: dict, path: str) -> dict:
     set_default(config, "edit_uri", None, str)
 
     # Set defaults for repository name settings
+    docs_dir = config.get("docs_dir")
+    repo_names = {
+        "github.com": "GitHub",
+        "gitlab.com": "Gitlab",
+        "bitbucket.org": "Bitbucket"
+    }
+    edit_uris = {
+        "github.com": f"edit/master/{docs_dir}",
+        "gitlab.com": f"edit/master/{docs_dir}",
+        "bitbucket.org": f"src/default/{docs_dir}"
+    }
     repo_url = config.get("repo_url")
-    if repo_url and not config.get("repo_name"):
-        docs_dir = config.get("docs_dir")
+    if repo_url:
         host = urlparse(repo_url).hostname or ""
-        if host == "github.com":
-            set_default(config, "repo_name", "GitHub", str)
-            set_default(config, "edit_uri", f"edit/master/{docs_dir}", str)
-        elif host == "gitlab.com":
-            set_default(config, "repo_name", "GitLab", str)
-            set_default(config, "edit_uri", f"edit/master/{docs_dir}", str)
-        elif host == "bitbucket.org":
-            set_default(config, "repo_name", "Bitbucket", str)
-            set_default(config, "edit_uri", f"src/default/{docs_dir}", str)
+        if not config.get("repo_name") and host in repo_names:
+            set_default(config, "repo_name", repo_names[host], str)
         elif host:
             config["repo_name"] = host.split(".")[0].title()
+        if host in edit_uris:
+            set_default(config, "edit_uri", edit_uris[host], str)
 
     # Remove trailing slash from edit_uri if present
     edit_uri = config.get("edit_uri")
@@ -282,73 +285,13 @@ def _apply_defaults(config: dict, path: str) -> dict:
             set_default(toggle, "name", None, str)
 
     # Set defaults for extra settings
+    if "extra" in config and not isinstance(config["extra"], dict):
+        raise ConfigurationError("The 'extra' setting must be a mapping/dictionary.")
     extra = set_default(config, "extra", {}, dict)
-    set_default(extra, "homepage", None, str)
-    set_default(extra, "scope", None, str)
-    set_default(extra, "annotate", {}, dict)
-    set_default(extra, "tags", {}, dict)
-    set_default(extra, "generator", True, bool)
+
+    if "polyfills" in extra and not isinstance(extra["polyfills"], list):
+        raise ConfigurationError("The 'extra.polyfills' setting must be a list.")
     set_default(extra, "polyfills", [], list)
-    set_default(extra, "analytics", None, dict)
-
-    # Set defaults for extra analytics settings
-    analytics = extra.get("analytics")
-    if analytics:
-        set_default(analytics, "provider", None, str)
-        set_default(analytics, "property", None, str)
-        set_default(analytics, "feedback", None, dict)
-
-        # Set defaults for extra analytics feedback settings
-        feedback = analytics.get("feedback")
-        if feedback:
-            set_default(feedback, "title", None, str)
-            set_default(feedback, "ratings", [], list)
-
-            # Set defaults for each rating entry
-            ratings = feedback.setdefault("ratings", [])
-            for entry in ratings:
-                set_default(entry, "icon", None, str)
-                set_default(entry, "name", None, str)
-                set_default(entry, "data", None, str)
-                set_default(entry, "note", None, str)
-
-    # Set defaults for extra consent settings
-    consent = extra.setdefault("consent", None)
-    if consent:
-        set_default(consent, "title", None, str)
-        set_default(consent, "description", None, str)
-        set_default(consent, "actions", [], list)
-
-        # Set defaults for extra consent cookie settings
-        cookies = consent.setdefault("cookies", {})
-        for key, value in cookies.items():
-            if isinstance(value, str):
-                cookies[key] = {"name": value, "checked": False}
-
-            # Set defaults for each cookie entry
-            set_default(cookies[key], "name", None, str)
-            set_default(cookies[key], "checked", False, bool)
-
-    # Set defaults for extra social settings
-    social = extra.setdefault("social", [])
-    for entry in social:
-        set_default(entry, "icon", None, str)
-        set_default(entry, "name", None, str)
-        set_default(entry, "link", None, str)
-
-    # Set defaults for extra alternate settings
-    alternate = extra.setdefault("alternate", [])
-    for entry in alternate:
-        set_default(entry, "name", None, str)
-        set_default(entry, "link", None, str)
-        set_default(entry, "lang", None, str)
-
-    # Set defaults for extra version settings
-    version = extra.setdefault("version", None)
-    if version:
-        set_default(version, "provider", None, str)
-        set_default(version, "default", None, str)
-        set_default(version, "alias", False, bool)
 
     # Ensure all non-existent values are all empty strings (for now)
     config["extra"] = _convert_extra(extra)
@@ -425,31 +368,54 @@ def _apply_defaults(config: dict, path: str) -> dict:
     tabbed = config["mdx_configs"].get("pymdownx.tabbed", {})
     if isinstance(tabbed.get("slugify"), dict):
         object = tabbed["slugify"].get("object", "pymdownx.slugs.slugify")
-        tabbed["slugify"] = partial(
-            _resolve(object), tabbed["slugify"].get("kwds")
-        )
+        tabbed["slugify"] = _resolve(object)(**tabbed["slugify"].get("kwds", {}))
+
+    # Table of contents extension configuration - resolve slugification function
+    toc = config["mdx_configs"]["toc"]
+    if isinstance(toc.get("slugify"), dict):
+        object = toc["slugify"].get("object", "pymdownx.slugs.slugify")
+        toc["slugify"] = _resolve(object)(**toc["slugify"].get("kwds", {}))
 
     # Superfences extension configuration - resolve format function
     superfences = config["mdx_configs"].get("pymdownx.superfences", {})
     for fence in superfences.get("custom_fences", []):
         if isinstance(fence.get("format"), str):
             fence["format"] = _resolve(fence.get("format"))
+        elif isinstance(fence.get("format"), dict):
+            object = fence["format"].get("object", "pymdownx.superfences.fence_code_format")
+            fence["format"] = _resolve(object)(**fence["format"].get("kwds", {}))
+        if isinstance(fence.get("validator"), str):
+            fence["validator"] = _resolve(fence.get("validator"))
+        elif isinstance(fence.get("validator"), dict):
+            object = fence["validator"].get("object")
+            callable_object = _resolve(object) if object else lambda *args, **kwargs: True
+            fence["validator"] = callable_object(**fence["validator"].get("kwds", {}))
 
     # Ensure the table of contents title is initialized, as it's used inside
     # the template, and the table of contents extension is always defined
     config["mdx_configs"]["toc"].setdefault("title", None)
+    config["mdx_configs_hash"] = _hash(mdx_configs)
 
     # Convert plugins configuration
     config["plugins"] = _convert_plugins(config.get("plugins", []), config)
+
+    # mkdocstrings configuration
+    if "mkdocstrings" in config["plugins"]:
+        mkdocstrings_config = config["plugins"]["mkdocstrings"]["config"]
+        if mkdocstrings_config.pop("enabled", True):
+            mkdocstrings_config["markdown_extensions"] = [
+                {ext: mdx_configs.get(ext, {})} for ext in markdown_extensions
+            ]
+            config["markdown_extensions"].append("mkdocstrings")
+            config["mdx_configs"]["mkdocstrings"] = mkdocstrings_config
+
     return config
 
 
 def set_default(
-    entry: dict, key: str, default: Any, data_type: type = None
-) -> any:
-    """
-    Set a key to a default value if it isn't set, and optionally cast it to the specified data type.
-    """
+    entry: dict, key: str, default: Any, data_type: type | None = None
+) -> Any:
+    """Set a key to a default value if it isn't set, and optionally cast it to the specified data type."""
     if key in entry and entry[key] is None:
         del entry[key]
 
@@ -461,16 +427,22 @@ def set_default(
         try:
             entry[key] = data_type(entry[key])
         except (ValueError, TypeError) as e:
-            raise ValueError(f"Failed to cast key '{key}' to {data_type}: {e}")
+            raise ValueError(
+                f"Failed to cast key '{key}' to {data_type}: {e}"
+            ) from e
 
     # Return the resulting value
     return entry[key]
 
 
+def _hash(data: Any) -> int:
+    """Compute a hash for the given data."""
+    hash = hashlib.sha1(pickle.dumps(data))  # noqa: S324
+    return int(hash.hexdigest(), 16) % (2**64)
+
+
 def _convert_extra(data: dict | list) -> dict | list:
-    """
-    Recursively convert all None values in a dictionary or list to empty strings.
-    """
+    """Recursively convert all None values in a dictionary or list to empty strings."""
     if isinstance(data, dict):
         # Process each key-value pair in the dictionary
         return {
@@ -479,7 +451,7 @@ def _convert_extra(data: dict | list) -> dict | list:
             else ("" if value is None else value)
             for key, value in data.items()
         }
-    elif isinstance(data, list):
+    if isinstance(data, list):
         # Process each item in the list
         return [
             _convert_extra(item)
@@ -487,14 +459,11 @@ def _convert_extra(data: dict | list) -> dict | list:
             else ("" if item is None else item)
             for item in data
         ]
-    else:
-        return data
+    return data
 
 
-def _resolve(symbol: str):
-    """
-    Resolve a symbol to its corresponding Python object.
-    """
+def _resolve(symbol: str) -> Any:
+    """Resolve a symbol to its corresponding Python object."""
     module_path, func_name = symbol.rsplit(".", 1)
     module = importlib.import_module(module_path)
     return getattr(module, func_name)
@@ -503,17 +472,15 @@ def _resolve(symbol: str):
 # -----------------------------------------------------------------------------
 
 
-def _convert_nav(nav: dict) -> dict:
-    """
-    Convert MkDocs navigation
-    """
+def _convert_nav(nav: list) -> list:
+    """Convert MkDocs navigation."""
     return [_convert_nav_item(entry) for entry in nav]
 
 
-def _convert_nav_item(item: str | dict | list) -> dict:
-    """
-    Convert MkDocs shorthand navigation structure into something more manageable
-    as we need to annotate each item with a title, URL, icon, and children.
+def _convert_nav_item(item: str | dict | list) -> dict | list:
+    """Convert MkDocs shorthand navigation structure into something more manageable.
+
+    We need to annotate each item with a title, URL, icon, and children.
     """
     if isinstance(item, str):
         return {
@@ -527,19 +494,19 @@ def _convert_nav_item(item: str | dict | list) -> dict:
         }
 
     # Handle Title: URL
-    elif isinstance(item, dict):
+    if isinstance(item, dict):
         for title, value in item.items():
             if isinstance(value, str):
                 return {
                     "title": str(title),
-                    "url": value,
+                    "url": value.strip(),
                     "canonical_url": None,
                     "meta": None,
                     "children": [],
-                    "is_index": _is_index(value),
+                    "is_index": _is_index(value.strip()),
                     "active": False,
                 }
-            elif isinstance(value, list):
+            if isinstance(value, list):
                 return {
                     "title": str(title),
                     "url": None,
@@ -549,28 +516,25 @@ def _convert_nav_item(item: str | dict | list) -> dict:
                     "is_index": False,
                     "active": False,
                 }
+            raise TypeError(f"Unknown nav item value type: {type(value)}")
 
     # Handle a list of items
     elif isinstance(item, list):
         return [_convert_nav_item(child) for child in item]
-    else:
-        raise ValueError(f"Unknown nav item type: {type(item)}")
+
+    raise TypeError(f"Unknown nav item type: {type(item)}")
 
 
 def _is_index(path: str) -> bool:
-    """
-    Returns, whether the given path points to a section index.
-    """
-    return path.endswith(("index.md", "README.md"))
+    """Returns, whether the given path points to a section index."""
+    return os.path.basename(path) in ("index.md", "README.md")
 
 
 # -----------------------------------------------------------------------------
 
 
-def _convert_extra_javascript(value: list[any]) -> list:
-    """
-    Ensure extra_javascript uses a structured format.
-    """
+def _convert_extra_javascript(value: list) -> list:
+    """Ensure extra_javascript uses a structured format."""
     for i, item in enumerate(value):
         if isinstance(item, str):
             value[i] = {
@@ -585,9 +549,7 @@ def _convert_extra_javascript(value: list[any]) -> list:
             item.setdefault("async", False)
             item.setdefault("defer", False)
         else:
-            raise ValueError(
-                f"Unknown extra_javascript item type: {type(item)}"
-            )
+            raise TypeError(f"Unknown extra_javascript item type: {type(item)}")
 
     # Return resulting value
     return value
@@ -596,12 +558,10 @@ def _convert_extra_javascript(value: list[any]) -> list:
 # -----------------------------------------------------------------------------
 
 
-def _convert_markdown_extensions(value: any):
-    """
-    Convert Markdown extensions configuration to what Python Markdown expects.
-    """
+def _convert_markdown_extensions(value: Any) -> tuple[list[str], dict]:
+    """Convert Markdown extensions configuration to what Python Markdown expects."""
     markdown_extensions = ["toc", "tables"]
-    mdx_configs = {"toc": {}, "tables": {}}
+    mdx_configs: dict[str, dict[str, Any]] = {"toc": {}, "tables": {}}
 
     # In case of Python Markdown Extensions, we allow to omit the necessary
     # quotes around the extension names, so we need to hoist the extensions
@@ -609,8 +569,24 @@ def _convert_markdown_extensions(value: any):
     # actually parse the configuration.
     if "pymdownx" in value:
         pymdownx = value.pop("pymdownx")
-        for ext, config in pymdownx.items():
-            value[f"pymdownx.{ext}"] = config
+        for ext, conf in pymdownx.items():
+            # Special case for blocks extension, which has another level of
+            # nesting. This is the only extension that requires this.
+            if ext == "blocks":
+                for block, config in conf.items():
+                    value[f"pymdownx.{ext}.{block}"] = config
+            else:
+                value[f"pymdownx.{ext}"] = conf
+
+    # Same as for Python Markdown extensions, see above
+    if "zensical" in value:
+        zensical = value.pop("zensical")
+        for ext, conf in zensical.items():
+            if ext == "extensions":
+                for key, config in conf.items():
+                    value[f"zensical.{ext}.{key}"] = config
+            else:
+                value[f"zensical.{ext}"] = conf
 
     # Extensions can be defined as a dict
     if isinstance(value, dict):
@@ -635,16 +611,13 @@ def _convert_markdown_extensions(value: any):
 # ----------------------------------------------------------------------------
 
 
-def _convert_plugins(value: any, config: dict) -> list:
-    """
-    Convert plugins configuration to something we can work with.
-    """
+def _convert_plugins(value: Any, config: dict) -> dict:
+    """Convert plugins configuration to something we can work with."""
     plugins = {}
 
     # Plugins can be defined as a dict
     if isinstance(value, dict):
-        for name, data in value.items():
-            plugins[name] = data
+        plugins.update(value)
 
     # Plugins can also be defined as a list
     else:
@@ -701,8 +674,7 @@ def _convert_plugins(value: any, config: dict) -> list:
 def _yaml_load(
     source: IO, loader: type[BaseLoader] | None = None
 ) -> dict[str, Any]:
-    """
-    Load configuration file and resolve environment variables and parent files.
+    """Load configuration file and resolve environment variables and parent files.
 
     Note that INHERIT is only a bandaid that was introduced to allow for some
     degree of modularity, but with serious shortcomings. Zensical will use a
@@ -717,12 +689,12 @@ def _yaml_load(
             source.read()
             .replace("material.extensions", "zensical.extensions")
             .replace("materialx", "zensical.extensions"),
-            Loader=Loader,
+            Loader=Loader,  # noqa: S506
         )
     except YAMLError as e:
         raise ConfigurationError(
             f"Encountered an error parsing the configuration file: {e}"
-        )
+        ) from e
     if config is None:
         return {}
 
@@ -736,7 +708,7 @@ def _yaml_load(
             raise ConfigurationError(
                 f"Inherited config file '{relpath}' doesn't exist at '{abspath}'."
             )
-        with open(abspath, "r") as fd:
+        with open(abspath, encoding="utf-8") as fd:
             parent = _yaml_load(fd, loader)
         config = always_merger.merge(parent, config)
 
@@ -744,9 +716,11 @@ def _yaml_load(
     return config
 
 
-def _construct_env_tag(loader: yaml.Loader, node: yaml.Node):
-    """
-    Assign value of ENV variable referenced at node.
+def _construct_env_tag(
+    loader: yaml.Loader,
+    node: yaml.ScalarNode | yaml.SequenceNode | yaml.MappingNode,
+) -> Any:
+    """Assign value of ENV variable referenced at node.
 
     MkDocs supports the use of !ENV to reference environment variables in YAML
     configuration files. We won't likely support this in Zensical, but for now
@@ -775,7 +749,7 @@ def _construct_env_tag(loader: yaml.Loader, node: yaml.Node):
     else:
         raise ConstructorError(
             context=f"expected a scalar or sequence node, but found {node.id}",
-            start_mark=node.start_mark,
+            context_mark=node.start_mark,
         )
 
     # Resolve environment variable