From 33aa573efb17b13e7b9da77e29aeccb3fbddd8e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 25 Jul 2024 17:02:25 +0200 Subject: [PATCH 01/13] deps: Depend on mkdocs-autorefs v1 --- pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index e7c02d17..0b1cdad9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,8 +35,8 @@ dependencies = [ "Markdown>=3.3", "MarkupSafe>=1.1", "mkdocs>=1.4", - "mkdocs-autorefs>=0.3.1", - "platformdirs>=2.2.0", + "mkdocs-autorefs>=1.0", + "platformdirs>=2.2", "pymdown-extensions>=6.3", "importlib-metadata>=4.6; python_version < '3.10'", "typing-extensions>=4.1; python_version < '3.10'", From 3ee464ad2dc0bc12972b9d4d829dd3ab757202ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 4 Aug 2024 15:45:48 +0200 Subject: [PATCH 02/13] chore: Clean up after template upgrade --- .github/ISSUE_TEMPLATE/question.md | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/question.md diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md deleted file mode 100644 index c65012f1..00000000 --- a/.github/ISSUE_TEMPLATE/question.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: Question -about: Ask a question about mkdocstrings usage -title: '' -labels: question -assignees: '' - ---- - -**Add detailed information, like** -- project folder structure (`tree -L 2`) -- `mkdocs.yml` configuration file contents -- *mkdocstrings* version: [e.g. 0.10.2] From b9bd56722b7e52a141f84d9be6bc36e237577367 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 4 Aug 2024 15:46:02 +0200 Subject: [PATCH 03/13] docs: List griffe-typedoc and mkdocstrings-c in insiders projects --- docs/insiders/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index f164974c..ccbca99a 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -59,7 +59,9 @@ a handful of them, [thanks to our awesome sponsors][sponsors]! --> data_source = [ "docs/insiders/goals.yml", ("griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"), + ("griffe-typedoc", "https://mkdocstrings.github.io/griffe-typedoc/", "insiders/goals.yml"), ("griffe-warnings-deprecated", "https://mkdocstrings.github.io/griffe-warnings-deprecated/", "insiders/goals.yml"), + ("mkdocstrings-c", "https://mkdocstrings.github.io/c/", "insiders/goals.yml"), ("mkdocstrings-python", "https://mkdocstrings.github.io/python/", "insiders/goals.yml"), ("mkdocstrings-shell", "https://mkdocstrings.github.io/shell/", "insiders/goals.yml"), ("mkdocstrings-typescript", "https://mkdocstrings.github.io/typescript/", "insiders/goals.yml"), From d01d6f537497c88734c159e2a92c3aa5d64fe589 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 4 Aug 2024 16:09:39 +0200 Subject: [PATCH 04/13] docs: Don't auto-highlight inline code --- mkdocs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 3522d7db..e76dc8f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -106,8 +106,6 @@ markdown_extensions: emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.highlight: pygments_lang_class: true -- pymdownx.inlinehilite: - style_plain_text: python - pymdownx.magiclink - pymdownx.snippets: base_path: [!relative $config_dir] From 4a47f4fec5418de70dc1e2508c93c5c15d4c728f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 4 Aug 2024 16:10:15 +0200 Subject: [PATCH 05/13] docs: Update handlers lists --- README.md | 9 ++++++--- docs/usage/handlers.md | 11 +++++++---- mkdocs.yml | 2 ++ 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 80822c52..4ada4cb0 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,12 @@ Come have a chat or ask questions on our [Gitter channel](https://gitter.im/mkdo just like *MkDocs*, *mkdocstrings* is written in Python but is language-agnostic. It means you can use it with any programming language, as long as there is a [**handler**](https://mkdocstrings.github.io/reference/handlers/base/) for it. - We currently have [handlers](https://mkdocstrings.github.io/handlers/overview/) - for the [Crystal](https://mkdocstrings.github.io/crystal/), [Python](https://mkdocstrings.github.io/python/), - and [VBA](https://pypi.org/project/mkdocstrings-vba/) languages, + We currently have [handlers](https://mkdocstrings.github.io/handlers/overview/) for the + [C](https://mkdocstrings.github.io/c/), + [Crystal](https://mkdocstrings.github.io/crystal/), + [Python](https://mkdocstrings.github.io/python/), + [TypeScript](https://mkdocstrings.github.io/typescript/), and + [VBA](https://pypi.org/project/mkdocstrings-vba/) languages, as well as for [shell scripts/libraries](https://mkdocstrings.github.io/shell/). Maybe you'd like to add another one to the list? :wink: diff --git a/docs/usage/handlers.md b/docs/usage/handlers.md index 10b8aac4..6871d72b 100644 --- a/docs/usage/handlers.md +++ b/docs/usage/handlers.md @@ -4,10 +4,13 @@ A handler is what makes it possible to collect and render documentation for a pa ## Available handlers -- Crystal -- Python -- Python (Legacy) -- Shell +- [C](https://mkdocstrings.github.io/c/){ .external } [:octicons-heart-fill-24:{ .heart .pulse title="Sponsors only" }](../insiders/index.md) +- [Crystal](https://mkdocstrings.github.io/crystal/){ .external } +- [Python](https://mkdocstrings.github.io/python/){ .external } +- [Python (Legacy)](https://mkdocstrings.github.io/python-legacy/){ .external } +- [Shell](https://mkdocstrings.github.io/shell/){ .external } [:octicons-heart-fill-24:{ .heart .pulse title="Sponsors only" }](../insiders/index.md) +- [TypeScript](https://mkdocstrings.github.io/typescript/){ .external } [:octicons-heart-fill-24:{ .heart .pulse title="Sponsors only" }](../insiders/index.md) +- [VBA](https://pypi.org/project/mkdocstrings-vba/){ .external } ## About the Python handlers diff --git a/mkdocs.yml b/mkdocs.yml index e76dc8f8..2f6d9947 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,10 +24,12 @@ nav: - Theming: usage/theming.md - Handlers: usage/handlers.md - All handlers: + - C: https://mkdocstrings.github.io/c/ - Crystal: https://mkdocstrings.github.io/crystal/ - Python: https://mkdocstrings.github.io/python/ - Python (Legacy): https://mkdocstrings.github.io/python-legacy/ - Shell: https://mkdocstrings.github.io/shell/ + - TypeScript: https://mkdocstrings.github.io/typescript/ - VBA: https://pypi.org/project/mkdocstrings-vba - Guides: - Recipes: recipes.md From 4787d032ee1d253eeb57243aee8ce7a9fb2056a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 4 Aug 2024 16:10:31 +0200 Subject: [PATCH 06/13] docs: Add FastAPI to "Used by" section in readme --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 4ada4cb0..03e82afb 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ Come have a chat or ask questions on our [Gitter channel](https://gitter.im/mkdo *mkdocstrings* is used by well-known companies, projects and scientific teams: [Ansible](https://molecule.readthedocs.io/configuration/), [Apache](https://streampipes.apache.org/docs/docs/python/latest/reference/client/client/), +[FastAPI](https://fastapi.tiangolo.com/reference/fastapi/), [Google](https://docs.kidger.site/jaxtyping/api/runtime-type-checking/), [Jitsi](https://jitsi.github.io/jiwer/reference/alignment/), [Microsoft](https://microsoft.github.io/presidio/api/analyzer_python/), From 8041ef35c4b3379d74d2afec75c967315b2b5f36 Mon Sep 17 00:00:00 2001 From: Jeremy Feng <44312563+jeremy-feng@users.noreply.github.com> Date: Wed, 7 Aug 2024 18:59:48 +0800 Subject: [PATCH 07/13] docs: Update code highlight lines --- docs/recipes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/recipes.md b/docs/recipes.md index 953f3879..cb2d9eb1 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -204,7 +204,7 @@ plugins: Then, the previous script is updated like so: -```python title="scripts/gen_ref_pages.py" hl_lines="7 23 31 32" +```python title="scripts/gen_ref_pages.py" hl_lines="7 24 32 33" """Generate the code reference pages and navigation.""" from pathlib import Path @@ -278,7 +278,7 @@ Well, this is possible thanks to a third plugin: Update the script like this: -```python title="scripts/gen_ref_pages.py" hl_lines="20 21" +```python title="scripts/gen_ref_pages.py" hl_lines="21 22" """Generate the code reference pages and navigation.""" from pathlib import Path From c6ca5228339926da8f140dbed4602043add51416 Mon Sep 17 00:00:00 2001 From: fritz-astronomer <80706212+fritz-astronomer@users.noreply.github.com> Date: Thu, 15 Aug 2024 05:48:07 -0400 Subject: [PATCH 08/13] docs: Fix dead link --- docs/usage/theming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/theming.md b/docs/usage/theming.md index b5d6f7b3..09ee92fd 100644 --- a/docs/usage/theming.md +++ b/docs/usage/theming.md @@ -62,7 +62,7 @@ to modify small part of the templates without copy-pasting the whole files. See the documentation about templates for: - the Crystal handler: https://mkdocstrings.github.io/crystal/styling.html -- the Python handler: https://mkdocstrings.github.io/python/customization/#templates +- the Python handler: https://mkdocstrings.github.io/python/usage/customization/#templates #### Debugging From 52fad1163127e94d130bbbd479b51e8e38405f8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 1 Sep 2024 20:36:36 +0200 Subject: [PATCH 09/13] style: Format --- duties.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/duties.py b/duties.py index 655cfdfc..3d287036 100644 --- a/duties.py +++ b/duties.py @@ -54,7 +54,7 @@ def changelog(ctx: Context, bump: str = "") -> None: @duty(pre=["check_quality", "check_types", "check_docs", "check_dependencies", "check-api"]) -def check(ctx: Context) -> None: # noqa: ARG001 +def check(ctx: Context) -> None: """Check it all!""" From 28565f97f21bf81b2bc554679c641fba3f639882 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 1 Sep 2024 23:39:24 +0200 Subject: [PATCH 10/13] build: Upgrade Python-Markdown lower bound to 3.6 Version 3.6 refactored TOC sanitation, and we rely on it for TOC labels. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 0b1cdad9..d660b0ee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,7 +32,7 @@ classifiers = [ dependencies = [ "click>=7.0", "Jinja2>=2.11.1", - "Markdown>=3.3", + "Markdown>=3.6", "MarkupSafe>=1.1", "mkdocs>=1.4", "mkdocs-autorefs>=1.0", From 3c878b7f53f2b13a61f2facb5a91a949955e688e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 1 Sep 2024 23:40:50 +0200 Subject: [PATCH 11/13] chore: Upgrade mkdocs-redirects lower bound to avoid deprecation warning --- devdeps.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devdeps.txt b/devdeps.txt index 2a987e77..90b0f095 100644 --- a/devdeps.txt +++ b/devdeps.txt @@ -28,6 +28,6 @@ mkdocs-git-committers-plugin-2>=2.3 mkdocs-literate-nav>=0.6 mkdocs-material>=9.5 mkdocs-minify-plugin>=0.8 -mkdocs-redirects>=1.2 +mkdocs-redirects>=1.2.1 mkdocstrings[python]>=0.25 tomli>=2.0; python_version < '3.11' From b63e72691a8f92dd59b56304125de4a19e0d028c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 1 Sep 2024 23:58:57 +0200 Subject: [PATCH 12/13] feat: Allow hooking into autorefs when converting Markdown docstrings Based-on-PR-autorefs#46: https://github.com/mkdocstrings/autorefs/pull/46 --- pyproject.toml | 2 +- src/mkdocstrings/handlers/base.py | 12 +++++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index d660b0ee..6985ba3f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,7 +35,7 @@ dependencies = [ "Markdown>=3.6", "MarkupSafe>=1.1", "mkdocs>=1.4", - "mkdocs-autorefs>=1.0", + "mkdocs-autorefs>=1.2", "platformdirs>=2.2", "pymdown-extensions>=6.3", "importlib-metadata>=4.6; python_version < '3.10'", diff --git a/src/mkdocstrings/handlers/base.py b/src/mkdocstrings/handlers/base.py index d86e9df1..44c79e35 100644 --- a/src/mkdocstrings/handlers/base.py +++ b/src/mkdocstrings/handlers/base.py @@ -8,13 +8,14 @@ import importlib import sys from pathlib import Path -from typing import Any, BinaryIO, ClassVar, Iterable, Iterator, Mapping, MutableMapping, Sequence, cast +from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterable, Iterator, Mapping, MutableMapping, Sequence, cast from xml.etree.ElementTree import Element, tostring from jinja2 import Environment, FileSystemLoader from markdown import Markdown from markdown.extensions.toc import TocTreeprocessor from markupsafe import Markup +from mkdocs_autorefs.references import AutorefsInlineProcessor from mkdocstrings.handlers.rendering import ( HeadingShiftingTreeprocessor, @@ -32,6 +33,9 @@ else: from importlib.metadata import entry_points +if TYPE_CHECKING: + from mkdocs_autorefs.references import AutorefsHookInterface + CollectorItem = Any @@ -253,6 +257,7 @@ def do_convert_markdown( html_id: str = "", *, strip_paragraph: bool = False, + autoref_hook: AutorefsHookInterface | None = None, ) -> Markup: """Render Markdown text; for use inside templates. @@ -269,12 +274,17 @@ def do_convert_markdown( treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level # type: ignore[attr-defined] treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--" # type: ignore[attr-defined] treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph # type: ignore[attr-defined] + + if autoref_hook: + self._md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook # type: ignore[attr-defined] + try: return Markup(self._md.convert(text)) finally: treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0 # type: ignore[attr-defined] treeprocessors[IdPrependingTreeprocessor.name].id_prefix = "" # type: ignore[attr-defined] treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False # type: ignore[attr-defined] + self._md.inlinePatterns[AutorefsInlineProcessor.name].hook = None # type: ignore[attr-defined] self._md.reset() def do_heading( From b1aa042f26c346dbdbf10efb20612c0dc5f8834f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 2 Sep 2024 00:29:01 +0200 Subject: [PATCH 13/13] chore: Prepare release 0.26.0 --- CHANGELOG.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c092ed42..2617c8cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ 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). +## [0.26.0](https://github.com/mkdocstrings/mkdocstrings/releases/tag/0.26.0) - 2024-09-02 + +[Compare with 0.25.2](https://github.com/mkdocstrings/mkdocstrings/compare/0.25.2...0.26.0) + +### Build + +- Upgrade Python-Markdown lower bound to 3.6 ([28565f9](https://github.com/mkdocstrings/mkdocstrings/commit/28565f97f21bf81b2bc554679c641fba3f639882) by Timothée Mazzucotelli). + +### Dependencies + +- Depend on mkdocs-autorefs v1 ([33aa573](https://github.com/mkdocstrings/mkdocstrings/commit/33aa573efb17b13e7b9da77e29aeccb3fbddd8e8) by Timothée Mazzucotelli). + +### Features + +- Allow hooking into autorefs when converting Markdown docstrings ([b63e726](https://github.com/mkdocstrings/mkdocstrings/commit/b63e72691a8f92dd59b56304125de4a19e0d028c) by Timothée Mazzucotelli). [Based-on-PR-autorefs#46](https://github.com/mkdocstrings/autorefs/pull/46) + ## [0.25.2](https://github.com/mkdocstrings/mkdocstrings/releases/tag/0.25.2) - 2024-07-25 [Compare with 0.25.1](https://github.com/mkdocstrings/mkdocstrings/compare/0.25.1...0.25.2)