diff --git a/ci-constraints.txt b/ci-constraints.txt index 8dd68c6..bbedc19 100644 --- a/ci-constraints.txt +++ b/ci-constraints.txt @@ -1,3 +1,3 @@ -mkdocstrings==0.26.1 -griffe==1.3.1 +mkdocstrings==0.30.0 +griffe==1.12.1 mkdocs-material==9.2.1 diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 60828f9..5a71e3f 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -4,8 +4,7 @@ from __future__ import annotations -import copy -from collections import ChainMap +from copy import deepcopy from pathlib import Path from typing import ( Any, @@ -16,9 +15,9 @@ ) from griffe import patch_loggers -from markdown import Markdown +from mkdocs.config.defaults import MkDocsConfig from mkdocs.exceptions import PluginError -from mkdocstrings.handlers.base import BaseHandler, CollectionError +from mkdocstrings import BaseHandler, CollectionError from mkdocstrings.loggers import get_logger from ._crossref import do_crossref, do_multi_crossref @@ -51,12 +50,12 @@ def __init__(self, *, base_dir: Path, encoding: str, **kwargs: Any) -> None: self.base_dir = base_dir self.encoding = encoding - name: str = "vba" + name: str = "vba" # type: ignore[misc] """ The handler's name. """ - domain: str = "vba" + domain: str = "vba" # type: ignore[misc] """ The cross-documentation domain/language for this handler. """ @@ -107,6 +106,17 @@ def __init__(self, *, base_dir: Path, encoding: str, **kwargs: Any) -> None: **`docstring_section_style`** | `str` | The style used to render docstring sections. Options: `table`, `list`, `spacy`. | `table` """ + def get_options(self, local_options: Mapping[str, Any]) -> Dict[str, Any]: + """Combine the default options with the local options. + + Arguments: + local_options: The options provided in Markdown pages. + + Returns: + The combined options. + """ + return deepcopy({**self.default_config, **local_options}) + def collect( self, identifier: str, @@ -141,32 +151,32 @@ def collect( def render( self, data: VbaModuleInfo, - config: Mapping[str, Any], + options: MutableMapping[str, Any], + *, + locale: str | None = None, ) -> str: - final_config = ChainMap(dict(copy.deepcopy(config)), self.default_config) template = self.env.get_template(f"module.html") # Heading level is a "state" variable, that will change at each step # of the rendering recursion. Therefore, it's easier to use it as a plain value # than as an item in a dictionary. - heading_level = final_config["heading_level"] + heading_level = options["heading_level"] try: - final_config["members_order"] = Order(final_config["members_order"]) + options["members_order"] = Order(options["members_order"]) except ValueError: choices = "', '".join(item.value for item in Order) raise PluginError( - f"Unknown members_order '{final_config['members_order']}', choose between '{choices}'." + f"Unknown members_order '{options['members_order']}', choose between '{choices}'." ) return template.render( - config=final_config, + config=options, module=data, heading_level=heading_level, root=True, ) - def update_env(self, md: Markdown, config: Dict[Any, Any]) -> None: - super().update_env(md, config) + def update_env(self, config: Dict[Any, Any]) -> None: self.env.trim_blocks = True self.env.lstrip_blocks = True self.env.keep_trailing_newline = False @@ -174,42 +184,48 @@ def update_env(self, md: Markdown, config: Dict[Any, Any]) -> None: self.env.filters["multi_crossref"] = do_multi_crossref self.env.filters["order_members"] = do_order_members - def get_anchors(self, data: VbaModuleInfo) -> Tuple[str, ...]: + def get_aliases(self, identifier: str) -> Tuple[str, ...]: + """Get the aliases of the given identifier. + + Aliases are used to register secondary URLs in mkdocs-autorefs, + to make sure cross-references work with any location of the same object. + + Arguments: + identifier: The identifier to get aliases for. + + Returns: + A tuple of aliases for the given identifier. + """ + try: + data = self.collect(identifier, {}) + except CollectionError: + return () return data.path.as_posix(), *(p.signature.name for p in data.procedures) def get_handler( *, - theme: str = "material", - custom_templates: str | None = None, - config_file_path: str | None = None, encoding: str = "latin1", + tool_config: MkDocsConfig | None = None, **kwargs: Any, ) -> VbaHandler: """ Get a new `VbaHandler`. Arguments: - theme: The theme to use when rendering contents. - custom_templates: Directory containing custom templates. - config_file_path: The MkDocs configuration file path. encoding: The encoding to use when reading VBA files. Excel exports .bas and .cls files as `latin1`. See https://en.wikipedia.org/wiki/ISO/IEC_8859-1 . + tool_config: SSG configuration. kwargs: Extra keyword arguments that we don't use. Returns: An instance of `VbaHandler`. """ - return VbaHandler( - base_dir=( - Path(config_file_path).resolve().parent - if config_file_path - else Path(".").resolve() - ), - encoding=encoding, - handler="vba", - theme=theme, - custom_templates=custom_templates, + base_dir = ( + Path(getattr(tool_config, "config_file_path", None) or "./mkdocs.yml") + .resolve() + .parent ) + return VbaHandler(base_dir=base_dir, encoding=encoding, **kwargs) diff --git a/mypy-requirements.txt b/mypy-requirements.txt index fab278d..7f188ec 100644 --- a/mypy-requirements.txt +++ b/mypy-requirements.txt @@ -1,3 +1,3 @@ -mypy==1.11.2 -types-setuptools==75.* +mypy==1.17.* +types-setuptools==80.* types-Markdown==3.* diff --git a/setup.py b/setup.py index acfa5ff..fc2e0b2 100644 --- a/setup.py +++ b/setup.py @@ -28,7 +28,7 @@ "setuptools_scm", ], install_requires=[ - "mkdocstrings>=0.26.1,<1", + "mkdocstrings>=0.30,<1", "griffe>=1.3.1,<2", "mkdocs-material>=9.2,<10", ],