From c65217f39215a44750155387a89211bb6748ba23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 24 Jan 2025 13:20:34 +0100 Subject: [PATCH 1/9] Update handler for mkdocstrings 0.28 --- mkdocstrings_handlers/vba/_handler.py | 73 ++++++++++++++------------- setup.py | 2 +- 2 files changed, 40 insertions(+), 35 deletions(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 60828f9..9c9f260 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -4,11 +4,10 @@ from __future__ import annotations -import copy -from collections import ChainMap from pathlib import Path from typing import ( Any, + ClassVar, MutableMapping, Dict, Mapping, @@ -16,7 +15,7 @@ ) 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.loggers import get_logger @@ -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 {**self.default_config, **local_options} + def collect( self, identifier: str, @@ -141,32 +151,30 @@ def collect( def render( self, data: VbaModuleInfo, - config: Mapping[str, Any], + config: MutableMapping[str, Any], ) -> 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 = config["heading_level"] try: - final_config["members_order"] = Order(final_config["members_order"]) + config["members_order"] = Order(config["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 '{config['members_order']}', choose between '{choices}'." ) return template.render( - config=final_config, + config=config, 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 +182,39 @@ 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", - **kwargs: Any, -) -> VbaHandler: +def get_handler(*, 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/setup.py b/setup.py index acfa5ff..e4fcf4c 100644 --- a/setup.py +++ b/setup.py @@ -28,7 +28,7 @@ "setuptools_scm", ], install_requires=[ - "mkdocstrings>=0.26.1,<1", + "mkdocstrings>=0.28,<1", "griffe>=1.3.1,<2", "mkdocs-material>=9.2,<10", ], From de7b3a0e0b9650748beca4b3593dffc01fad512a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 24 Jan 2025 13:27:18 +0100 Subject: [PATCH 2/9] fixup! Update handler for mkdocstrings 0.28 --- mkdocstrings_handlers/vba/_handler.py | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 9c9f260..9e032e1 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -108,10 +108,10 @@ def __init__(self, *, base_dir: Path, encoding: str, **kwargs: Any) -> None: 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. """ @@ -184,13 +184,13 @@ def update_env(self, config: Dict[Any, Any]) -> None: 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. """ @@ -201,7 +201,12 @@ def get_aliases(self, identifier: str) -> Tuple[str, ...]: return data.path.as_posix(), *(p.signature.name for p in data.procedures) -def get_handler(*, encoding: str = "latin1", tool_config: MkDocsConfig | None = None, **kwargs: Any) -> VbaHandler: +def get_handler( + *, + encoding: str = "latin1", + tool_config: MkDocsConfig | None = None, + **kwargs: Any, +) -> VbaHandler: """ Get a new `VbaHandler`. @@ -216,5 +221,9 @@ def get_handler(*, encoding: str = "latin1", tool_config: MkDocsConfig | None = Returns: An instance of `VbaHandler`. """ - base_dir = Path(getattr(tool_config, "config_file_path", None) or "./mkdocs.yml").resolve().parent + base_dir = ( + Path(getattr(tool_config, "config_file_path", None) or "./mkdocs.yml") + .resolve() + .parent + ) return VbaHandler(base_dir=base_dir, encoding=encoding, **kwargs) From e60fdeeb928f7450deb45dd0e48bd81e7c53e757 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 24 Jan 2025 13:27:56 +0100 Subject: [PATCH 3/9] fixup! Update handler for mkdocstrings 0.28 --- mkdocstrings_handlers/vba/_handler.py | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 9e032e1..38cb093 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -7,7 +7,6 @@ from pathlib import Path from typing import ( Any, - ClassVar, MutableMapping, Dict, Mapping, From 172b7a3132741a8eb790e14c32f5d3f90d8c3a78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Aug 2025 18:54:28 +0200 Subject: [PATCH 4/9] fixup! Update handler for mkdocstrings 0.28 --- mkdocstrings_handlers/vba/_handler.py | 5 +++-- setup.py | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 38cb093..866370b 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -4,6 +4,7 @@ from __future__ import annotations +from copy import deepcopy from pathlib import Path from typing import ( Any, @@ -114,8 +115,8 @@ def get_options(self, local_options: Mapping[str, Any]) -> Dict[str, Any]: Returns: The combined options. """ - return {**self.default_config, **local_options} - + return deepcopy({**self.default_config, **local_options}) + def collect( self, identifier: str, diff --git a/setup.py b/setup.py index e4fcf4c..fc2e0b2 100644 --- a/setup.py +++ b/setup.py @@ -28,7 +28,7 @@ "setuptools_scm", ], install_requires=[ - "mkdocstrings>=0.28,<1", + "mkdocstrings>=0.30,<1", "griffe>=1.3.1,<2", "mkdocs-material>=9.2,<10", ], From 4bdc6f16d6ab53959b6479ce754e320a250f2be7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Aug 2025 18:55:34 +0200 Subject: [PATCH 5/9] fixup! Update handler for mkdocstrings 0.28 --- ci-constraints.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci-constraints.txt b/ci-constraints.txt index 8dd68c6..c00122f 100644 --- a/ci-constraints.txt +++ b/ci-constraints.txt @@ -1,3 +1,3 @@ -mkdocstrings==0.26.1 +mkdocstrings==0.30.0 griffe==1.3.1 mkdocs-material==9.2.1 From 019d4f68a24e8b8d7941253638b59a17b7b84551 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Aug 2025 18:56:20 +0200 Subject: [PATCH 6/9] fixup! Update handler for mkdocstrings 0.28 --- mkdocstrings_handlers/vba/_handler.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 866370b..0684a99 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -116,7 +116,7 @@ def get_options(self, local_options: Mapping[str, Any]) -> Dict[str, Any]: The combined options. """ return deepcopy({**self.default_config, **local_options}) - + def collect( self, identifier: str, From c128c062c19c01b58552457789b2fafe385f4201 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Aug 2025 19:00:58 +0200 Subject: [PATCH 7/9] fixup! Update handler for mkdocstrings 0.28 --- mkdocstrings_handlers/vba/_handler.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocstrings_handlers/vba/_handler.py b/mkdocstrings_handlers/vba/_handler.py index 0684a99..43c875f 100644 --- a/mkdocstrings_handlers/vba/_handler.py +++ b/mkdocstrings_handlers/vba/_handler.py @@ -17,7 +17,7 @@ from griffe import patch_loggers 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 From 24468d1c4811d6f46edc53b7073a008000b43fd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Aug 2025 19:03:22 +0200 Subject: [PATCH 8/9] fixup! Update handler for mkdocstrings 0.28 --- mypy-requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mypy-requirements.txt b/mypy-requirements.txt index fab278d..cc2e5c5 100644 --- a/mypy-requirements.txt +++ b/mypy-requirements.txt @@ -1,3 +1,3 @@ -mypy==1.11.2 +mypy==1.17.1 types-setuptools==75.* types-Markdown==3.* From 161c89aa25f2bde9463a8888227ba43ccc783535 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 24 Aug 2025 19:06:14 +0200 Subject: [PATCH 9/9] fixup! Update handler for mkdocstrings 0.28 --- ci-constraints.txt | 2 +- mypy-requirements.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ci-constraints.txt b/ci-constraints.txt index c00122f..bbedc19 100644 --- a/ci-constraints.txt +++ b/ci-constraints.txt @@ -1,3 +1,3 @@ mkdocstrings==0.30.0 -griffe==1.3.1 +griffe==1.12.1 mkdocs-material==9.2.1 diff --git a/mypy-requirements.txt b/mypy-requirements.txt index cc2e5c5..7f188ec 100644 --- a/mypy-requirements.txt +++ b/mypy-requirements.txt @@ -1,3 +1,3 @@ -mypy==1.17.1 -types-setuptools==75.* +mypy==1.17.* +types-setuptools==80.* types-Markdown==3.*