From cc54d77f63ecb97c4bcc6fb1b447eddad6e842ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 27 Nov 2025 16:40:59 +0100 Subject: [PATCH 1/7] chore: Template upgrade --- .copier-answers.yml | 2 +- duties.py | 41 ++++++++++------------------------------- mkdocs.yml | 5 +---- 3 files changed, 12 insertions(+), 36 deletions(-) diff --git a/.copier-answers.yml b/.copier-answers.yml index 6c5d650e..dafd61dc 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier. -_commit: 1.11.1 +_commit: 1.11.2 _src_path: gh:pawamoy/copier-uv author_email: dev@pawamoy.fr author_fullname: Timothée Mazzucotelli diff --git a/duties.py b/duties.py index 04357dbb..653e2f0d 100644 --- a/duties.py +++ b/duties.py @@ -5,16 +5,12 @@ import os import re import sys -from contextlib import contextmanager -from importlib.metadata import version as pkgversion from pathlib import Path from typing import TYPE_CHECKING from duty import duty, tools if TYPE_CHECKING: - from collections.abc import Iterator - from duty.context import Context @@ -36,18 +32,6 @@ def pyprefix(title: str) -> str: return title -@contextmanager -def material_insiders() -> Iterator[bool]: - if "+insiders" in pkgversion("mkdocs-material"): - os.environ["MATERIAL_INSIDERS"] = "true" - try: - yield True - finally: - os.environ.pop("MATERIAL_INSIDERS") - else: - yield False - - def _get_changelog_version() -> str: changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$") with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file: @@ -84,11 +68,10 @@ def check_docs(ctx: Context) -> None: """Check if the documentation builds correctly.""" Path("htmlcov").mkdir(parents=True, exist_ok=True) Path("htmlcov/index.html").touch(exist_ok=True) - with material_insiders(): - ctx.run( - tools.mkdocs.build(strict=True, verbose=True), - title=pyprefix("Building documentation"), - ) + ctx.run( + tools.mkdocs.build(strict=True, verbose=True), + title=pyprefix("Building documentation"), + ) @duty(nofail=PY_VERSION == PY_DEV) @@ -120,22 +103,18 @@ def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000 host: The host to serve the docs from. port: The port to serve the docs on. """ - with material_insiders(): - ctx.run( - tools.mkdocs.serve(dev_addr=f"{host}:{port}").add_args(*cli_args), - title="Serving documentation", - capture=False, - ) + ctx.run( + tools.mkdocs.serve(dev_addr=f"{host}:{port}").add_args(*cli_args), + title="Serving documentation", + capture=False, + ) @duty def docs_deploy(ctx: Context) -> None: """Deploy the documentation to GitHub pages.""" os.environ["DEPLOY"] = "true" - with material_insiders() as insiders: - if not insiders: - ctx.run(lambda: False, title="Not deploying docs without Material for MkDocs Insiders!") - ctx.run(tools.mkdocs.gh_deploy(remote_name="org-pages", force=True), title="Deploying documentation") + ctx.run(tools.mkdocs.gh_deploy(force=True), title="Deploying documentation") @duty diff --git a/mkdocs.yml b/mkdocs.yml index 8250973b..d2c5085e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -188,10 +188,7 @@ plugins: reference/plugin.md: reference/api.md#mkdocstrings.plugin - minify: minify_html: !ENV [DEPLOY, false] -- group: - enabled: !ENV [MATERIAL_INSIDERS, false] - plugins: - - typeset +- typeset extra: social: From afefc0fbccc09f7b6f0c92cf3446434d241f1658 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 30 Nov 2025 15:40:34 +0100 Subject: [PATCH 2/7] chore: Fix docs-deploy duty --- duties.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/duties.py b/duties.py index 653e2f0d..0759f7a5 100644 --- a/duties.py +++ b/duties.py @@ -114,7 +114,7 @@ def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000 def docs_deploy(ctx: Context) -> None: """Deploy the documentation to GitHub pages.""" os.environ["DEPLOY"] = "true" - ctx.run(tools.mkdocs.gh_deploy(force=True), title="Deploying documentation") + ctx.run(tools.mkdocs.gh_deploy(remote_name="org-pages", force=True), title="Deploying documentation") @duty From b6a33e23ba411159253ee44d1b1fa63b9a9a7b7a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 6 Jan 2026 01:02:44 +0000 Subject: [PATCH 3/7] chore: Update sponsors section in README --- README.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index a486ed40..e28c653b 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,6 @@ See the [Usage](https://mkdocstrings.github.io/usage) section of the docs for mo
Silver sponsors

-Material for MkDocs
FastAPI
Pydantic

@@ -165,23 +164,18 @@ See the [Usage](https://mkdocstrings.github.io/usage) section of the docs for mo machow BenHammersley trevorWieland -laenan8466 MarcoGorelli analog-cbarber OdinManiac rstudio-sponsorship schlich -SuperCowPowers butterlyn livingbio NemetschekAllplan EricJayHartman 15r10nk -cdwilson activeloopai roboflow -wrath-codes -leodevian cmclaughlin blaisep RapidataAI @@ -190,9 +184,10 @@ See the [Usage](https://mkdocstrings.github.io/usage) section of the docs for mo blakeNaccarato ChargeStorm Alphadelta14 +Cusp-AI

-*And 8 more private sponsor(s).* +*And 7 more private sponsor(s).* From f43f1ee2cd38a0dba64fc7d0db3c5ffb037bf7f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 15 Jan 2026 15:06:16 +0100 Subject: [PATCH 4/7] refactor: Support cross-references in Zensical PR-812: https://github.com/mkdocstrings/mkdocstrings/pull/812 --- src/mkdocstrings/_internal/extension.py | 42 +++++++++++++++++++++---- 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/src/mkdocstrings/_internal/extension.py b/src/mkdocstrings/_internal/extension.py index 3a6f4530..da713a07 100644 --- a/src/mkdocstrings/_internal/extension.py +++ b/src/mkdocstrings/_internal/extension.py @@ -34,7 +34,7 @@ from markdown.extensions import Extension from markdown.treeprocessors import Treeprocessor from mkdocs.exceptions import PluginError -from mkdocs_autorefs import AutorefsConfig, AutorefsPlugin +from mkdocs_autorefs import AutorefsConfig, AutorefsExtension, AutorefsPlugin from mkdocstrings._internal.handlers.base import BaseHandler, CollectionError, CollectorItem, Handlers from mkdocstrings._internal.loggers import get_logger @@ -316,17 +316,26 @@ class MkdocstringsExtension(Extension): It cannot work outside of `mkdocstrings`. """ - def __init__(self, handlers: Handlers, autorefs: AutorefsPlugin, **kwargs: Any) -> None: + def __init__( + self, + handlers: Handlers, + autorefs: AutorefsPlugin, + *, + autorefs_extension: bool = False, + **kwargs: Any, + ) -> None: """Initialize the object. Arguments: handlers: The handlers container. autorefs: The autorefs plugin instance. + autorefs_extension: Whether the autorefs extension must be registered. **kwargs: Keyword arguments used by `markdown.extensions.Extension`. """ super().__init__(**kwargs) self._handlers = handlers self._autorefs = autorefs + self._autorefs_extension = autorefs_extension def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent method's name) """Register the extension. @@ -336,6 +345,12 @@ def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent me Arguments: md: A `markdown.Markdown` instance. """ + md.registerExtension(self) + + # Zensical integration: get the current page from the Zensical-specific preprocessor. + if "zensical_current_page" in md.preprocessors: + self._autorefs.current_page = md.preprocessors["zensical_current_page"] # type: ignore[assignment] + md.parser.blockprocessors.register( AutoDocProcessor(md, handlers=self._handlers, autorefs=self._autorefs), "mkdocstrings", @@ -352,6 +367,9 @@ def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent me priority=4, # Right after 'toc'. ) + if self._autorefs_extension: + AutorefsExtension(self._autorefs).extendMarkdown(md) + # ----------------------------------------------------------------------------- # The following is only used by Zensical. The goal is to provide temporary @@ -421,10 +439,22 @@ def makeExtension( # noqa: N802 tool_config=tool_config, ) - handlers_instance._download_inventories() - autorefs = AutorefsPlugin() autorefs.config = AutorefsConfig() - autorefs.scan_toc = False + autorefs.config.resolve_closest = True + autorefs.config.link_titles = "auto" + autorefs.config.strip_title_tags = "auto" + autorefs.scan_toc = True + autorefs._link_titles = "external" + autorefs._strip_title_tags = False - return MkdocstringsExtension(handlers=handlers_instance, autorefs=autorefs) + handlers_instance._download_inventories() + register = autorefs.register_url + for identifier, url in handlers_instance._yield_inventory_items(): + register(identifier, url) + + return MkdocstringsExtension( + handlers=handlers_instance, + autorefs=autorefs, + autorefs_extension=True, + ) From 0edd18af00fa5907bb31e8309ecf5ad4309da552 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 15 Jan 2026 15:06:54 +0100 Subject: [PATCH 5/7] chore: Clean up after v1 --- CHANGELOG.md | 5 +---- docs/usage/handlers.md | 2 +- mkdocs.yml | 7 ------- pyproject.toml | 2 +- src/mkdocstrings/_internal/handlers/base.py | 4 ++-- 5 files changed, 5 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9def4ba8..4fac770e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -952,8 +952,6 @@ See issue [#74](https://github.com/pawamoy/mkdocstrings/issues/74). ### Features - Prepare for new `pytkdocs` version ([336421a](https://github.com/pawamoy/mkdocstrings/commit/336421af95d752671276c2e88c5c173bff4093cc)). Add options `filters` and `members` to the Python collector to reflect the new `pytkdocs` options. - See [the default configuration of the Python collector](https://pawamoy.github.io/mkdocstrings/reference/handlers/python/#mkdocstrings.handlers.python.PythonCollector.DEFAULT_CONFIG). - ## [0.9.1](https://github.com/pawamoy/mkdocstrings/releases/tag/0.9.1) - 2020-03-21 @@ -979,8 +977,7 @@ No identified breaking changes for end-users. - **Better cross-references:** cross-references now not only work between documented objects (between all languages, given the objects' identifiers are unique), but also for every heading of your Markdown pages. - **Configuration options:** the rendering of Python documentation can now be configured, - (globally and locally thanks to the handlers system), - [check the docs!](https://pawamoy.github.io/mkdocstrings/reference/handlers/python/#mkdocstrings.handlers.python.PythonRenderer.DEFAULT_CONFIG) + (globally and locally thanks to the handlers system). Also see the [recommended CSS](https://pawamoy.github.io/mkdocstrings/handlers/python/#recommended-style). - **Proper logging messages:** `mkdocstrings` now logs debug, warning and error messages, useful when troubleshooting. diff --git a/docs/usage/handlers.md b/docs/usage/handlers.md index efdaccd1..6f326431 100644 --- a/docs/usage/handlers.md +++ b/docs/usage/handlers.md @@ -205,7 +205,7 @@ to use the templates of another handler. In you handler, override the ```python from pathlib import Path -from mkdocstrings.handlers.base import BaseHandler +from mkdocstrings import BaseHandler class CobraHandler(BaseHandler): diff --git a/mkdocs.yml b/mkdocs.yml index d2c5085e..8423ce25 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -179,13 +179,6 @@ plugins: handlers/overview.md: usage/handlers.md reference/mkdocstrings.md: reference/api.md reference/index.md: reference/api.md#mkdocstrings - reference/extension.md: reference/api.md#mkdocstrings.extension - reference/handlers/index.md: reference/api.md#mkdocstrings.handlers - reference/handlers/base.md: reference/api.md#mkdocstrings.handlers.base - reference/handlers/rendering.md: reference/api.md#mkdocstrings.handlers.rendering - reference/inventory.md: reference/api.md#mkdocstrings.inventory - reference/loggers.md: reference/api.md#mkdocstrings.loggers - reference/plugin.md: reference/api.md#mkdocstrings.plugin - minify: minify_html: !ENV [DEPLOY, false] - typeset diff --git a/pyproject.toml b/pyproject.toml index 2b3d6c17..7f033477 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -113,7 +113,7 @@ ci = [ "mkdocs-minify-plugin>=0.8", "mkdocs-redirects>=1.2.1", "mkdocs-section-index>=0.3", - "mkdocstrings-python>=1.16.2", + "mkdocstrings-python>=2.0", # YORE: EOL 3.10: Remove line. "tomli>=2.0; python_version < '3.11'", ] diff --git a/src/mkdocstrings/_internal/handlers/base.py b/src/mkdocstrings/_internal/handlers/base.py index 2eb9b3e6..05808ef9 100644 --- a/src/mkdocstrings/_internal/handlers/base.py +++ b/src/mkdocstrings/_internal/handlers/base.py @@ -241,7 +241,7 @@ def collect(self, identifier: str, options: HandlerOptions) -> CollectorItem: Arguments: identifier: An identifier for which to collect data. For example, in Python, - it would be 'mkdocstrings.handlers' to collect documentation about the handlers module. + it would be 'mkdocstrings.BaseHandler' to collect documentation about the BaseHandler class. It can be anything that you can feed to the tool of your choice. options: The final configuration options. @@ -560,7 +560,7 @@ def get_handler_config(self, name: str) -> dict: def get_handler(self, name: str, handler_config: dict | None = None) -> BaseHandler: """Get a handler thanks to its name. - This function dynamically imports a module named "mkdocstrings.handlers.NAME", calls its + This function dynamically imports a module named "mkdocstrings_handlers.NAME", calls its `get_handler` method to get an instance of a handler, and caches it in dictionary. It means that during one run (for each reload when serving, or once when building), a handler is instantiated only once, and reused for each "autodoc" instruction asking for it. From d37d9079e5381350b2e3ffc5f698e28a5b572d36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 17 Jan 2026 19:20:23 +0100 Subject: [PATCH 6/7] refactor: Support manual cross-references in Zensical too --- src/mkdocstrings/_internal/extension.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/mkdocstrings/_internal/extension.py b/src/mkdocstrings/_internal/extension.py index da713a07..b9174aec 100644 --- a/src/mkdocstrings/_internal/extension.py +++ b/src/mkdocstrings/_internal/extension.py @@ -387,7 +387,7 @@ def extendMarkdown(self, md: Markdown) -> None: # noqa: N802 (casing: parent me } -def _split_configs(markdown_extensions: list[str | dict]) -> tuple[list[str], dict[str, Any]]: +def _split_configs(markdown_extensions: list[str | dict]) -> tuple[list[str | Extension], dict[str, Any]]: # Split markdown extensions and their configs from mkdocs.yml mdx: list[str] = [] mdx_config: dict[str, Any] = {} @@ -399,7 +399,7 @@ def _split_configs(markdown_extensions: list[str | dict]) -> tuple[list[str], di mdx.append(key) mdx_config[key] = value break # Only one item per dict - return mdx, mdx_config + return mdx, mdx_config # type: ignore[return-value] class _ToolConfig: @@ -426,6 +426,17 @@ def makeExtension( # noqa: N802 mdx, mdx_config = _split_configs(markdown_extensions or []) tool_config = _ToolConfig(config_file_path=config_file_path) + autorefs = AutorefsPlugin() + autorefs.config = AutorefsConfig() + autorefs.config.resolve_closest = True + autorefs.config.link_titles = "auto" + autorefs.config.strip_title_tags = "auto" + autorefs.scan_toc = True + autorefs._link_titles = "external" + autorefs._strip_title_tags = False + + mdx.append(AutorefsExtension(autorefs)) + handlers_instance = Handlers( theme="material", default=default_handler or _default_config["default_handler"], @@ -439,15 +450,6 @@ def makeExtension( # noqa: N802 tool_config=tool_config, ) - autorefs = AutorefsPlugin() - autorefs.config = AutorefsConfig() - autorefs.config.resolve_closest = True - autorefs.config.link_titles = "auto" - autorefs.config.strip_title_tags = "auto" - autorefs.scan_toc = True - autorefs._link_titles = "external" - autorefs._strip_title_tags = False - handlers_instance._download_inventories() register = autorefs.register_url for identifier, url in handlers_instance._yield_inventory_items(): From cb8a3c781674b8e23cf0048955d70358d7bab49e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 19 Jan 2026 12:36:12 +0100 Subject: [PATCH 7/7] chore: Prepare release 1.0.1 --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fac770e..5e8050e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [1.0.1](https://github.com/mkdocstrings/mkdocstrings/releases/tag/1.0.1) - 2026-01-19 + +[Compare with 1.0.0](https://github.com/mkdocstrings/mkdocstrings/compare/1.0.0...1.0.1) + +### Code Refactoring + +- Support manual cross-references in Zensical too ([d37d907](https://github.com/mkdocstrings/mkdocstrings/commit/d37d9079e5381350b2e3ffc5f698e28a5b572d36) by Timothée Mazzucotelli). +- Support cross-references in Zensical ([f43f1ee](https://github.com/mkdocstrings/mkdocstrings/commit/f43f1ee2cd38a0dba64fc7d0db3c5ffb037bf7f7) by Timothée Mazzucotelli). [PR-812](https://github.com/mkdocstrings/mkdocstrings/pull/812) + ## [1.0.0](https://github.com/mkdocstrings/mkdocstrings/releases/tag/1.0.0) - 2025-11-27 [Compare with 0.30.1](https://github.com/mkdocstrings/mkdocstrings/compare/0.30.1...1.0.0)