mkdocstrings-python 1.11.1__tar.gz → 1.12.0__tar.gz

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ 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).
 
 <!-- insertion marker -->
+## [1.12.0](https://github.com/mkdocstrings/python/releases/tag/1.12.0) - 2024-10-12
+
+<small>[Compare with 1.11.1](https://github.com/mkdocstrings/python/compare/1.11.1...1.12.0)</small>
+
+### Build
+
+- Drop support for Python 3.8 ([6615c91](https://github.com/mkdocstrings/python/commit/6615c91cdc035bc0c2fdd12f3952ff84f5e1c04e) by Timothée Mazzucotelli).
+
+### Features
+
+- Auto-summary of members ([7f9757d](https://github.com/mkdocstrings/python/commit/7f9757d1584555edebc56f1aefe6cc8242e6c8bb) by Timothée Mazzucotelli).
+- Render function overloads ([0f2c25c](https://github.com/mkdocstrings/python/commit/0f2c25c9ed7f6c5c93ff13df214f02edfd3a4cb1) by Timothée Mazzucotelli).
+- Parameter headings, more automatic cross-references ([0176b83](https://github.com/mkdocstrings/python/commit/0176b83f21ae02d345489c93cca3baf51f8bc58c) by Timothée Mazzucotelli).
+
+### Code Refactoring
+
+- Declare default CSS symbol colors under :host as well ([3b9dba2](https://github.com/mkdocstrings/python/commit/3b9dba2709a8668e379c6ce1536cb1714971b3f4) by James McDonnell). [PR-186](https://github.com/mkdocstrings/python/pull/186)
+
 ## [1.11.1](https://github.com/mkdocstrings/python/releases/tag/1.11.1) - 2024-09-03
 
 <small>[Compare with 1.11.0](https://github.com/mkdocstrings/python/compare/1.11.0...1.11.1)</small>

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/CONTRIBUTING.md

@@ -23,12 +23,11 @@ make setup
 > You can install it with:
 >
 > ```bash
-> python3 -m pip install --user pipx
-> pipx install uv
+> curl -LsSf https://astral.sh/uv/install.sh | sh
 > ```
 >
 > Now you can try running `make setup` again,
-> or simply `uv install`.
+> or simply `uv sync`.
 
 You now have the dependencies installed.
 

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mkdocstrings-python
-Version: 1.11.1
+Version: 1.12.0
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License: ISC
@@ -9,14 +9,15 @@ Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Documentation
 Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Project-URL: Homepage, https://mkdocstrings.github.io/python
@@ -27,7 +28,7 @@ Project-URL: Issues, https://github.com/mkdocstrings/python/issues
 Project-URL: Discussions, https://github.com/mkdocstrings/python/discussions
 Project-URL: Gitter, https://gitter.im/mkdocstrings/python
 Project-URL: Funding, https://github.com/sponsors/pawamoy
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Requires-Dist: mkdocstrings>=0.26
 Requires-Dist: mkdocs-autorefs>=1.2
 Requires-Dist: griffe>=0.49

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/config/ruff.toml

@@ -1,4 +1,4 @@
-target-version = "py38"
+target-version = "py39"
 line-length = 120
 
 [lint]

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/docs/usage/configuration/headings.md

@@ -59,7 +59,6 @@ plugins:
 
 ## `parameter_headings`
 
-[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
 [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/docs/usage/configuration/members.md

@@ -552,7 +552,6 @@ package
 
 ## `summary`
 
-[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
 [:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0)
 
 - **:octicons-package-24: Type <code><autoref identifier="bool" optional>bool</autoref> | <autoref identifier="dict" optional>dict</autoref>[<autoref identifier="str" optional>str</autoref>, <autoref identifier="bool" optional>bool</autoref>]</code>  :material-equal: `False`{ title="default value" }**

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/duties.py

@@ -7,11 +7,13 @@ import sys
 from contextlib import contextmanager
 from importlib.metadata import version as pkgversion
 from pathlib import Path
-from typing import TYPE_CHECKING, Iterator
+from typing import TYPE_CHECKING
 
 from duty import duty, tools
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from duty.context import Context
 
 
@@ -53,7 +55,7 @@ def changelog(ctx: Context, bump: str = "") -> None:
     ctx.run(tools.git_changelog(bump=bump or None), title="Updating changelog")
 
 
-@duty(pre=["check_quality", "check_types", "check_docs", "check-api"])
+@duty(pre=["check-quality", "check-types", "check-docs", "check-api"])
 def check(ctx: Context) -> None:
     """Check it all!"""
 
@@ -116,23 +118,33 @@ def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000
 
 
 @duty
-def docs_deploy(ctx: Context) -> None:
-    """Deploy the documentation to GitHub pages."""
+def docs_deploy(ctx: Context, *, force: bool = False) -> None:
+    """Deploy the documentation to GitHub pages.
+
+    Parameters:
+        force: Whether to force deployment, even from non-Insiders version.
+    """
     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!")
-        origin = ctx.run("git config --get remote.origin.url", silent=True)
+        origin = ctx.run("git config --get remote.origin.url", silent=True, allow_overrides=False)
         if "pawamoy-insiders/mkdocstrings-python" in origin:
             ctx.run(
                 "git remote add upstream git@github.com:mkdocstrings/python",
                 silent=True,
                 nofail=True,
+                allow_overrides=False,
             )
             ctx.run(
                 tools.mkdocs.gh_deploy(remote_name="upstream", force=True),
                 title="Deploying documentation",
             )
+        elif force:
+            ctx.run(
+                tools.mkdocs.gh_deploy(force=True),
+                title="Deploying documentation",
+            )
         else:
             ctx.run(
                 lambda: False,

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/mkdocs.yml

@@ -180,9 +180,10 @@ plugins:
           signature_crossrefs: true
           summary: true
           unwrap_annotated: true
-- git-committers:
+- git-revision-date-localized:
     enabled: !ENV [DEPLOY, false]
-    repository: mkdocstrings/python
+    enable_creation_date: true
+    type: timeago
 - minify:
     minify_html: !ENV [DEPLOY, false]
 - group:

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/pyproject.toml

@@ -11,7 +11,7 @@ authors = [
     { name = "Timothée Mazzucotelli", email = "dev@pawamoy.fr" },
 ]
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 keywords = []
 dynamic = []
 classifiers = [
@@ -20,14 +20,15 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Documentation",
     "Topic :: Software Development",
+    "Topic :: Software Development :: Documentation",
     "Topic :: Utilities",
     "Typing :: Typed",
 ]
@@ -36,7 +37,7 @@ dependencies = [
     "mkdocs-autorefs>=1.2",
     "griffe>=0.49",
 ]
-version = "1.11.1"
+version = "1.12.0"
 
 [project.license]
 text = "ISC"
@@ -69,7 +70,6 @@ source-includes = [
     "scripts",
     "share",
     "tests",
-    "devdeps.txt",
     "duties.py",
     "mkdocs.yml",
     "*.md",
@@ -80,3 +80,31 @@ source-includes = [
 data = [
     { path = "share/**/*", relative-to = "." },
 ]
+
+[tool.uv]
+dev-dependencies = [
+    "editables>=0.5",
+    "build>=1.2",
+    "git-changelog>=2.5",
+    "twine>=5.1",
+    "duty>=1.4",
+    "ruff>=0.4",
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "pytest-randomly>=3.15",
+    "pytest-xdist>=3.6",
+    "mypy>=1.10",
+    "types-markdown>=3.6",
+    "types-pyyaml>=6.0",
+    "black>=24.4",
+    "markdown-callouts>=0.4",
+    "markdown-exec>=1.8",
+    "mkdocs>=1.6",
+    "mkdocs-coverage>=1.0",
+    "mkdocs-gen-files>=0.5",
+    "mkdocs-git-revision-date-localized-plugin>=1.2",
+    "mkdocs-literate-nav>=0.6",
+    "mkdocs-material>=9.5",
+    "mkdocs-minify-plugin>=0.8",
+    "tomli>=2.0; python_version < '3.11'",
+]

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/scripts/gen_credits.py

@@ -5,17 +5,18 @@ from __future__ import annotations
 import os
 import sys
 from collections import defaultdict
+from collections.abc import Iterable
 from importlib.metadata import distributions
 from itertools import chain
 from pathlib import Path
 from textwrap import dedent
-from typing import Dict, Iterable, Union
+from typing import Union
 
 from jinja2 import StrictUndefined
 from jinja2.sandbox import SandboxedEnvironment
 from packaging.requirements import Requirement
 
-# TODO: Remove once support for Python 3.10 is dropped.
+# YORE: EOL 3.10: Replace block with line 2.
 if sys.version_info >= (3, 11):
     import tomllib
 else:
@@ -26,11 +27,10 @@ with project_dir.joinpath("pyproject.toml").open("rb") as pyproject_file:
     pyproject = tomllib.load(pyproject_file)
 project = pyproject["project"]
 project_name = project["name"]
-with project_dir.joinpath("devdeps.txt").open() as devdeps_file:
-    devdeps = [line.strip() for line in devdeps_file if line.strip() and not line.strip().startswith(("-e", "#"))]
+devdeps = [dep for dep in pyproject["tool"]["uv"]["dev-dependencies"] if not dep.startswith("-e")]
 
-PackageMetadata = Dict[str, Union[str, Iterable[str]]]
-Metadata = Dict[str, PackageMetadata]
+PackageMetadata = dict[str, Union[str, Iterable[str]]]
+Metadata = dict[str, PackageMetadata]
 
 
 def _merge_fields(metadata: dict) -> PackageMetadata:

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/scripts/insiders.py

@@ -10,13 +10,16 @@ from dataclasses import dataclass
 from datetime import date, datetime, timedelta
 from itertools import chain
 from pathlib import Path
-from typing import Iterable, cast
+from typing import TYPE_CHECKING, cast
 from urllib.error import HTTPError
 from urllib.parse import urljoin
 from urllib.request import urlopen
 
 import yaml
 
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
 logger = logging.getLogger(f"mkdocs.logs.{__name__}")
 
 

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/scripts/make

@@ -9,12 +9,10 @@ import subprocess
 import sys
 from contextlib import contextmanager
 from pathlib import Path
+from textwrap import dedent
 from typing import Any, Iterator
 
-PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.8 3.9 3.10 3.11 3.12 3.13").split()
-
-exe = ""
-prefix = ""
+PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13 3.14").split()
 
 
 def shell(cmd: str, capture_output: bool = False, **kwargs: Any) -> str | None:
@@ -37,17 +35,13 @@ def environ(**kwargs: str) -> Iterator[None]:
         os.environ.update(original)
 
 
-def uv_install() -> None:
+def uv_install(venv: Path) -> None:
     """Install dependencies using uv."""
-    uv_opts = ""
-    if "UV_RESOLUTION" in os.environ:
-        uv_opts = f"--resolution={os.getenv('UV_RESOLUTION')}"
-    requirements = shell(f"uv pip compile {uv_opts} pyproject.toml devdeps.txt", capture_output=True)
-    shell("uv pip install -r -", input=requirements, text=True)
-    if "CI" not in os.environ:
-        shell("uv pip install --no-deps -e .")
-    else:
-        shell("uv pip install --no-deps .")
+    with environ(UV_PROJECT_ENVIRONMENT=str(venv), PYO3_USE_ABI3_FORWARD_COMPATIBILITY="1"):
+        if "CI" in os.environ:
+            shell("uv sync --no-editable")
+        else:
+            shell("uv sync")
 
 
 def setup() -> None:
@@ -59,7 +53,7 @@ def setup() -> None:
     default_venv = Path(".venv")
     if not default_venv.exists():
         shell("uv venv --python python")
-    uv_install()
+    uv_install(default_venv)
 
     if PYTHON_VERSIONS:
         for version in PYTHON_VERSIONS:
@@ -67,39 +61,22 @@ def setup() -> None:
             venv_path = Path(f".venvs/{version}")
             if not venv_path.exists():
                 shell(f"uv venv --python {version} {venv_path}")
-            with environ(VIRTUAL_ENV=str(venv_path.resolve())):
-                uv_install()
-
-
-def activate(path: str) -> None:
-    """Activate a virtual environment."""
-    global exe, prefix  # noqa: PLW0603
-
-    if (bin := Path(path, "bin")).exists():
-        activate_script = bin / "activate_this.py"
-    elif (scripts := Path(path, "Scripts")).exists():
-        activate_script = scripts / "activate_this.py"
-        exe = ".exe"
-        prefix = f"{path}/Scripts/"
-    else:
-        raise ValueError(f"make: activate: Cannot find activation script in {path}")
-
-    if not activate_script.exists():
-        raise ValueError(f"make: activate: Cannot find activation script in {path}")
-
-    exec(activate_script.read_text(), {"__file__": str(activate_script)})  # noqa: S102
+            with environ(UV_PROJECT_ENVIRONMENT=str(venv_path.resolve())):
+                uv_install(venv_path)
 
 
-def run(version: str, cmd: str, *args: str, **kwargs: Any) -> None:
+def run(version: str, cmd: str, *args: str, no_sync: bool = False, **kwargs: Any) -> None:
     """Run a command in a virtual environment."""
     kwargs = {"check": True, **kwargs}
+    uv_run = ["uv", "run"]
+    if no_sync:
+        uv_run.append("--no-sync")
     if version == "default":
-        activate(".venv")
-        subprocess.run([f"{prefix}{cmd}{exe}", *args], **kwargs)  # noqa: S603, PLW1510
+        with environ(UV_PROJECT_ENVIRONMENT=".venv"):
+            subprocess.run([*uv_run, cmd, *args], **kwargs)  # noqa: S603, PLW1510
     else:
-        activate(f".venvs/{version}")
-        os.environ["MULTIRUN"] = "1"
-        subprocess.run([f"{prefix}{cmd}{exe}", *args], **kwargs)  # noqa: S603, PLW1510
+        with environ(UV_PROJECT_ENVIRONMENT=f".venvs/{version}", MULTIRUN="1"):
+            subprocess.run([*uv_run, cmd, *args], **kwargs)  # noqa: S603, PLW1510
 
 
 def multirun(cmd: str, *args: str, **kwargs: Any) -> None:
@@ -124,10 +101,10 @@ def clean() -> None:
     for path in paths_to_clean:
         shell(f"rm -rf {path}")
 
-    cache_dirs = [".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__"]
-    for dirpath in Path(".").rglob("*"):
-        if any(dirpath.match(pattern) for pattern in cache_dirs) and not (dirpath.match(".venv") or dirpath.match(".venvs")):
-            shutil.rmtree(path, ignore_errors=True)
+    cache_dirs = {".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__"}
+    for dirpath in Path(".").rglob("*/"):
+        if dirpath.parts[0] not in (".venv", ".venvs") and dirpath.name in cache_dirs:
+            shutil.rmtree(dirpath, ignore_errors=True)
 
 
 def vscode() -> None:
@@ -143,22 +120,25 @@ def main() -> int:
         if len(args) > 1:
             run("default", "duty", "--help", args[1])
         else:
-            print("Available commands")  # noqa: T201
-            print("  help                  Print this help. Add task name to print help.")  # noqa: T201
-            print("  setup                 Setup all virtual environments (install dependencies).")  # noqa: T201
-            print("  run                   Run a command in the default virtual environment.")  # noqa: T201
-            print("  multirun              Run a command for all configured Python versions.")  # noqa: T201
-            print("  allrun                Run a command in all virtual environments.")  # noqa: T201
-            print("  3.x                   Run a command in the virtual environment for Python 3.x.")  # noqa: T201
-            print("  clean                 Delete build artifacts and cache files.")  # noqa: T201
-            print("  vscode                Configure VSCode to work on this project.")  # noqa: T201
-            try:
-                run("default", "python", "-V", capture_output=True)
-            except (subprocess.CalledProcessError, ValueError):
-                pass
-            else:
-                print("\nAvailable tasks")  # noqa: T201
-                run("default", "duty", "--list")
+            print(
+                dedent(
+                    """
+                    Available commands
+                      help                  Print this help. Add task name to print help.
+                      setup                 Setup all virtual environments (install dependencies).
+                      run                   Run a command in the default virtual environment.
+                      multirun              Run a command for all configured Python versions.
+                      allrun                Run a command in all virtual environments.
+                      3.x                   Run a command in the virtual environment for Python 3.x.
+                      clean                 Delete build artifacts and cache files.
+                      vscode                Configure VSCode to work on this project.
+                    """
+                ),
+                flush=True,
+            )  # noqa: T201
+            if os.path.exists(".venv"):
+                print("\nAvailable tasks", flush=True)  # noqa: T201
+                run("default", "duty", "--list", no_sync=True)
         return 0
 
     while args:

{mkdocstrings_python-1.11.1 → mkdocstrings_python-1.12.0}/src/mkdocstrings_handlers/python/handler.py

@@ -10,7 +10,7 @@ import sys
 from collections import ChainMap
 from contextlib import suppress
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar
 
 from griffe import (
     AliasResolutionError,
@@ -29,6 +29,8 @@ from mkdocstrings.loggers import get_logger
 from mkdocstrings_handlers.python import rendering
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator, Mapping, Sequence
+
     from markdown import Markdown
 
 
@@ -102,6 +104,7 @@ class PythonHandler(BaseHandler):
         "show_docstring_yields": True,
         "show_source": True,
         "show_bases": True,
+        "show_inheritance_diagram": False,
         "show_submodules": False,
         "group_by_category": True,
         "heading_level": 2,
@@ -116,6 +119,8 @@ class PythonHandler(BaseHandler):
         "summary": False,
         "show_labels": True,
         "unwrap_annotated": False,
+        "parameter_headings": False,
+        "modernize_annotations": False,
     }
     """Default handler configuration.
 
@@ -123,6 +128,7 @@ class PythonHandler(BaseHandler):
         find_stubs_package (bool): Whether to load stubs package (package-stubs) when extracting docstrings. Default `False`.
         allow_inspection (bool): Whether to allow inspecting modules when visiting them is not possible. Default: `True`.
         show_bases (bool): Show the base classes of a class. Default: `True`.
+        show_inheritance_diagram (bool): Show the inheritance diagram of a class using Mermaid. Default: `False`.
         show_source (bool): Show the source code of this object. Default: `True`.
         preload_modules (list[str] | None): Pre-load modules that are
             not specified directly in autodoc instructions (`::: identifier`).
@@ -136,6 +142,7 @@ class PythonHandler(BaseHandler):
 
     Attributes: Headings options:
         heading_level (int): The initial heading level to use. Default: `2`.
+        parameter_headings (bool): Whether to render headings for parameters (therefore showing parameters in the ToC). Default: `False`.
         show_root_heading (bool): Show the heading of the object at the root of the documentation tree
             (i.e. the object referenced by the identifier after `:::`). Default: `False`.
         show_root_toc_entry (bool): If the root heading is not shown, at least add a ToC entry for it. Default: `True`.
@@ -196,6 +203,7 @@ class PythonHandler(BaseHandler):
         separate_signature (bool): Whether to put the whole signature in a code block below the heading.
             If Black is installed, the signature is also formatted using it. Default: `False`.
         unwrap_annotated (bool): Whether to unwrap `Annotated` types to show only the type without the annotations. Default: `False`.
+        modernize_annotations (bool): Whether to modernize annotations, for example `Optional[str]` into `str | None`. Default: `False`.
     """
 
     def __init__(
@@ -270,7 +278,7 @@ class PythonHandler(BaseHandler):
     ) -> Iterator[tuple[str, str]]:
         """Yield items and their URLs from an inventory file streamed from `in_file`.
 
-        This implements mkdocstrings' `load_inventory` "protocol" (see [`mkdocstrings.plugin`][mkdocstrings.plugin]).
+        This implements mkdocstrings' `load_inventory` "protocol" (see [`mkdocstrings.plugin`][]).
 
         Arguments:
             in_file: The binary file-like object to read the inventory from.
@@ -424,7 +432,7 @@ class PythonHandler(BaseHandler):
         self.env.filters["format_signature"] = rendering.do_format_signature
         self.env.filters["format_attribute"] = rendering.do_format_attribute
         self.env.filters["filter_objects"] = rendering.do_filter_objects
-        self.env.filters["stash_crossref"] = lambda ref, length: ref
+        self.env.filters["stash_crossref"] = rendering.do_stash_crossref
         self.env.filters["get_template"] = rendering.do_get_template
         self.env.filters["as_attributes_section"] = rendering.do_as_attributes_section
         self.env.filters["as_functions_section"] = rendering.do_as_functions_section