From 3d838a96f77fa128cd6f2afa5ed0cb151ab225fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 25 Jul 2024 17:05:27 +0200 Subject: [PATCH 001/134] fix: Fix condition to display members (check all members, not just non-inherited ones) --- .../python/templates/material/_base/children.html.jinja | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja index 97fc7b57..22bbc8af 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja @@ -10,7 +10,7 @@ Context: heading_level (int): The HTML heading level to use. -#} -{% if obj.members %} +{% if obj.all_members %} {% block logs scoped %} {#- Logging block. From 004b18dd9cb37a6c9cb54d49f9e25f26d0bcaaa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 25 Jul 2024 12:19:19 -0300 Subject: [PATCH 002/134] docs: Fix links to Griffe API --- docs/usage/customization.md | 10 +++++----- src/mkdocstrings_handlers/python/handler.py | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 8eedadd1..5e82001e 100644 --- a/docs/usage/customization.md +++ b/docs/usage/customization.md @@ -302,7 +302,7 @@ and the Jinja context available in their scope. Available context: - `config`: The handler configuration (dictionary). -- `module`: The [Module][griffe.dataclasses.Module] instance. +- `module`: The [Module][griffe.Module] instance. #### `class.html` @@ -319,7 +319,7 @@ Available context: Available context: - `config`: The handler configuration (dictionary). -- `class`: The [Class][griffe.dataclasses.Class] instance. +- `class`: The [Class][griffe.Class] instance. #### `function.html` @@ -333,7 +333,7 @@ Available context: Available context: - `config`: The handler configuration (dictionary). -- `function`: The [Function][griffe.dataclasses.Function] instance. +- `function`: The [Function][griffe.Function] instance. #### `attribute.html` @@ -346,7 +346,7 @@ Available context: Available context: - `config`: The handler configuration (dictionary). -- `attribute`: The [Attribute][griffe.dataclasses.Attribute] instance. +- `attribute`: The [Attribute][griffe.Attribute] instance. #### Docstring sections @@ -368,7 +368,7 @@ and `docstring/yields.html`: Available context: -- `section`: The [DocstringSection][griffe.docstrings.dataclasses.DocstringSection] instance (see `DocstringSection*` subclasses). +- `section`: The [DocstringSection][griffe.DocstringSection] instance (see `DocstringSection*` subclasses). ### Syntax highlight in signatures diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 9cc60f31..a490e392 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -162,7 +162,7 @@ class PythonHandler(BaseHandler): Attributes: Docstrings options: docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`. - docstring_options (dict): The options for the docstring parser. See parsers under [`griffe.docstrings`][]. + docstring_options (dict): The options for the docstring parser. See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs. docstring_section_style (str): The style used to render docstring sections. Options: `table`, `list`, `spacy`. Default: `"table"`. merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`. show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`. From eff10ccf0fa1b2e73df912048a15c2d6406a2c8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 25 Jul 2024 17:30:45 +0200 Subject: [PATCH 003/134] refactor: Update code for Griffe 0.48 (removing deprecation warnings) Issue-173: https://github.com/mkdocstrings/python/issues/173 --- config/pytest.ini | 3 +++ pyproject.toml | 2 +- src/mkdocstrings_handlers/python/handler.py | 17 ++++++++++------- src/mkdocstrings_handlers/python/rendering.py | 15 +++++++-------- .../material/_base/attribute.html.jinja | 2 +- .../material/_base/children.html.jinja | 2 +- .../templates/material/_base/class.html.jinja | 2 +- .../material/_base/docstring.html.jinja | 2 +- .../_base/docstring/admonition.html.jinja | 2 +- .../_base/docstring/attributes.html.jinja | 2 +- .../material/_base/docstring/classes.html.jinja | 2 +- .../_base/docstring/examples.html.jinja | 2 +- .../_base/docstring/functions.html.jinja | 2 +- .../material/_base/docstring/modules.html.jinja | 2 +- .../_base/docstring/other_parameters.html.jinja | 2 +- .../_base/docstring/parameters.html.jinja | 2 +- .../material/_base/docstring/raises.html.jinja | 2 +- .../_base/docstring/receives.html.jinja | 2 +- .../material/_base/docstring/returns.html.jinja | 2 +- .../material/_base/docstring/warns.html.jinja | 2 +- .../material/_base/docstring/yields.html.jinja | 2 +- .../material/_base/expression.html.jinja | 4 ++-- .../material/_base/function.html.jinja | 2 +- .../templates/material/_base/module.html.jinja | 2 +- .../material/_base/signature.html.jinja | 2 +- .../_base/docstring/attributes.html.jinja | 2 +- .../_base/docstring/other_parameters.html.jinja | 2 +- .../_base/docstring/parameters.html.jinja | 2 +- .../_base/docstring/raises.html.jinja | 2 +- .../_base/docstring/receives.html.jinja | 2 +- .../_base/docstring/returns.html.jinja | 2 +- .../_base/docstring/warns.html.jinja | 2 +- .../_base/docstring/yields.html.jinja | 2 +- tests/test_handler.py | 3 +-- tests/test_rendering.py | 3 +-- 35 files changed, 53 insertions(+), 50 deletions(-) diff --git a/config/pytest.ini b/config/pytest.ini index 052a2f18..9d75f5c6 100644 --- a/config/pytest.ini +++ b/config/pytest.ini @@ -12,3 +12,6 @@ filterwarnings = error # TODO: remove once pytest-xdist 4 is released ignore:.*rsyncdir:DeprecationWarning:xdist + # TODO: remove once Griffe releases v1 + ignore:.*`get_logger`:DeprecationWarning:_griffe + ignore:.*`name`:DeprecationWarning:_griffe diff --git a/pyproject.toml b/pyproject.toml index 4e3629f4..1fc5bb58 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,7 +30,7 @@ classifiers = [ ] dependencies = [ "mkdocstrings>=0.25", - "griffe>=0.47", + "griffe>=0.48", ] [project.urls] diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index a490e392..d7c39699 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -12,12 +12,15 @@ from pathlib import Path from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterator, Mapping, Sequence -from griffe.collections import LinesCollection, ModulesCollection -from griffe.docstrings.parsers import Parser -from griffe.exceptions import AliasResolutionError -from griffe.extensions import load_extensions -from griffe.loader import GriffeLoader -from griffe.logger import patch_loggers +from griffe import ( + AliasResolutionError, + GriffeLoader, + LinesCollection, + ModulesCollection, + Parser, + load_extensions, + patch_logger, +) from mkdocstrings.extension import PluginError from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem from mkdocstrings.inventory import Inventory @@ -47,7 +50,7 @@ def chdir(path: str) -> Iterator[None]: # noqa: D103 logger = get_logger(__name__) -patch_loggers(get_logger) +patch_logger(get_logger) class PythonHandler(BaseHandler): diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index face49fe..b7fe3ad6 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -12,19 +12,20 @@ from pathlib import Path from typing import TYPE_CHECKING, Any, Callable, Match, Pattern, Sequence -from griffe.dataclasses import Alias, Object -from griffe.docstrings.dataclasses import ( +from griffe import ( + Alias, DocstringSectionAttributes, DocstringSectionClasses, DocstringSectionFunctions, DocstringSectionModules, + Object, ) from jinja2 import TemplateNotFound, pass_context, pass_environment from markupsafe import Markup from mkdocstrings.loggers import get_logger if TYPE_CHECKING: - from griffe.dataclasses import Attribute, Class, Function, Module + from griffe import Attribute, Class, Function, Module from jinja2 import Environment, Template from jinja2.runtime import Context from mkdocstrings.handlers.base import CollectorItem @@ -364,11 +365,9 @@ def _keep_object(name: str, filters: Sequence[tuple[Pattern, bool]]) -> bool: if regex.search(name): keep = not exclude if keep is None: - if rules == {False}: - # only included stuff, no match = reject - return False - # only excluded stuff, or included and excluded stuff, no match = keep - return True + # When we only include stuff, no match = reject. + # When we only exclude stuff, or include and exclude stuff, no match = keep. + return rules != {False} return keep diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 11bc4e77..0716b171 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -4,7 +4,7 @@ This template renders a Python attribute (or variable). This can be a module attribute or a class attribute. Context: - attribute (griffe.dataclasses.Attribute): The attribute to render. + attribute (griffe.Attribute): The attribute to render. root (bool): Whether this is the root object, injected with `:::` in a Markdown page. heading_level (int): The HTML heading level to use. config (dict): The configuration options. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja index 22bbc8af..c9c23156 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja @@ -4,7 +4,7 @@ This template iterates on members of a given object and renders them. It can group members by category (attributes, classes, functions, modules) or render them in a flat list. Context: - obj (griffe.dataclasses.Object): The object to render. + obj (griffe.Object): The object to render. config (dict): The configuration options. root_members (bool): Whether the object is the root object. heading_level (int): The HTML heading level to use. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index 67d00e34..27a91d13 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -3,7 +3,7 @@ This template renders a Python class. Context: - class (griffe.dataclasses.Class): The class to render. + class (griffe.Class): The class to render. root (bool): Whether this is the root object, injected with `:::` in a Markdown page. heading_level (int): The HTML heading level to use. config (dict): The configuration options. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja index f5095eb4..bc561b14 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja @@ -5,7 +5,7 @@ Griffe parses docstrings into a list of sections, each with a `kind` and a `valu This template can then iterate on these sections and render them according to the configuration. Context: - docstring_sections (list[griffe.docstrings.dataclasses.DocstringSection]): The list of docstring sections. + docstring_sections (list[griffe.DocstringSection]): The list of docstring sections. config (dict): The configuration dictionary. heading_level (int): The heading level to use for Markdown conversion. html_id (str): The HTML ID to use for Markdown conversion. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja index e3400280..70f462db 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html.jinja @@ -3,7 +3,7 @@ This template renders admonitions using the `details` HTML element. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAdmonition): The section to render. + section (griffe.DocstringSectionAdmonition): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja index e6c03dee..396e36dd 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented attributes in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja index 1aee5fd2..d21db25e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented classes in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja index 48913f80..39a90fa0 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented examples. It alternates between rendering text and code examples. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja index 53bda233..89ce923f 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented functions in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja index 239f7a55..49fc9d80 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented modules in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja index 7daabeda..a8730966 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented other parameters in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja index 3de6f4a9..a2db4900 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented parameters in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja index 79024057..21490f4e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented exceptions in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja index 2fcce8ef..86420b39 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented received values (generators) in the f specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja index 8feeb054..d402369a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented returned values in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja index 6143257d..702b9351 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented warnings in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja index d326c1fe..c83c478b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented yielded values (generators) in the fo specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja index 5a216e3e..67f02bb3 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja @@ -17,7 +17,7 @@ which is a tree-like structure representing a Python expression. This macro outputs a cross-reference to the given name. Parameters: - name (griffe.expressions.ExprName): The name to cross-reference. + name (griffe.ExprName): The name to cross-reference. annotation_path (str): Either "brief", "source", or "full". Returns: @@ -48,7 +48,7 @@ which is a tree-like structure representing a Python expression. {#- Render an expression. Parameters: - expression (griffe.expressions.Expr): The expression to render. + expression (griffe.Expr): The expression to render. annotations_path (str): Either "brief", "source", or "full". Returns: diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index 01f3e74a..3631b699 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -3,7 +3,7 @@ This template renders a Python function or method. Context: - function (griffe.dataclasses.Function): The function to render. + function (griffe.Function): The function to render. root (bool): Whether this is the root object, injected with `:::` in a Markdown page. heading_level (int): The HTML heading level to use. config (dict): The configuration options. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja index 06870b98..ae7d88d9 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja @@ -3,7 +3,7 @@ This template renders a Python module. Context: - module (griffe.dataclasses.Module): The module to render. + module (griffe.Module): The module to render. root (bool): Whether this is the root object, injected with `:::` in a Markdown page. heading_level (int): The HTML heading level to use. config (dict): The configuration options. diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja index 2d87986c..1107458c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja @@ -5,7 +5,7 @@ It iterates over the parameters of the function to rebuild the signature. The signature is the list of parameters of a function or method, including their names, default values, and annotations. Context: - function (griffe.dataclasses.Function): The function or method to render. + function (griffe.Function): The function or method to render. config (dict): The configuration options. -#} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja index 8df20e1c..f02e0b9c 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/attributes.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented attributes in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja index 4b416b65..34264133 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/other_parameters.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented other parameters in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja index 10bbd7ba..369912e7 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/parameters.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented parameters in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja index f350bc97..43d134f8 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/raises.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented exceptions in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja index 804a04a0..636c17e4 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/receives.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented received values (generators) in the f specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja index 0074327a..a00732d9 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/returns.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented returned values in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja index 88308b68..b445639c 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/warns.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented warnings in the format specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja index bd43955d..91097828 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/_base/docstring/yields.html.jinja @@ -4,7 +4,7 @@ This template renders a list of documented yielded values (generators) in the fo specified with the [`docstring_section_style`][] configuration option. Context: - section (griffe.docstrings.dataclasses.DocstringSectionAttributes): The section to render. + section (griffe.DocstringSectionAttributes): The section to render. -#} {% block logs scoped %} diff --git a/tests/test_handler.py b/tests/test_handler.py index 4ec7ee28..0717dc48 100644 --- a/tests/test_handler.py +++ b/tests/test_handler.py @@ -8,8 +8,7 @@ from typing import TYPE_CHECKING import pytest -from griffe.docstrings.dataclasses import DocstringSectionExamples, DocstringSectionKind -from griffe.tests import temporary_visited_module +from griffe import DocstringSectionExamples, DocstringSectionKind, temporary_visited_module from mkdocstrings_handlers.python.handler import CollectionError, PythonHandler, get_handler diff --git a/tests/test_rendering.py b/tests/test_rendering.py index 38d81dbb..1bab29d7 100644 --- a/tests/test_rendering.py +++ b/tests/test_rendering.py @@ -7,8 +7,7 @@ from typing import TYPE_CHECKING, Any import pytest -from griffe.collections import ModulesCollection -from griffe.tests import temporary_visited_module +from griffe import ModulesCollection, temporary_visited_module from mkdocstrings_handlers.python import rendering From 0817708af9181debdfd52765773a92018beab13a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 25 Jul 2024 17:58:21 +0200 Subject: [PATCH 004/134] chore: Prepare release 1.10.6 --- CHANGELOG.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91124a48..51d7d3cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ 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.10.6](https://github.com/mkdocstrings/python/releases/tag/1.10.6) - 2024-07-25 + +[Compare with 1.10.5](https://github.com/mkdocstrings/python/compare/1.10.5...1.10.6) + +### Bug Fixes + +- Fix condition to display members (check all members, not just non-inherited ones) ([3d838a9](https://github.com/mkdocstrings/python/commit/3d838a96f77fa128cd6f2afa5ed0cb151ab225fd) by Timothée Mazzucotelli). + +### Code Refactoring + +- Update code for Griffe 0.48 (removing deprecation warnings) ([eff10cc](https://github.com/mkdocstrings/python/commit/eff10ccf0fa1b2e73df912048a15c2d6406a2c8b) by Timothée Mazzucotelli). [Issue-173](https://github.com/mkdocstrings/python/issues/173) + ## [1.10.5](https://github.com/mkdocstrings/python/releases/tag/1.10.5) - 2024-06-19 [Compare with 1.10.4](https://github.com/mkdocstrings/python/compare/1.10.4...1.10.5) From c49bde8ec358927835edd17a690283f0dca64184 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 25 Jul 2024 18:15:43 +0200 Subject: [PATCH 005/134] chore: Template upgrade --- .copier-answers.yml | 2 +- .../{bug_report.md => 1-bug.md} | 2 +- .../{feature_request.md => 2-feature.md} | 0 .github/ISSUE_TEMPLATE/3-docs.md | 16 ++++++ .github/ISSUE_TEMPLATE/4-change.md | 18 ++++++ CONTRIBUTING.md | 12 ++-- devdeps.txt | 2 +- docs/.overrides/main.html | 8 ++- docs/.overrides/partials/comments.html | 57 +++++++++++++++++++ docs/index.md | 5 ++ docs/insiders/index.md | 4 ++ docs/js/feedback.js | 14 +++++ docs/license.md | 5 ++ mkdocs.yml | 15 +++++ pyproject.toml | 14 ++++- scripts/make | 19 +++++-- 16 files changed, 173 insertions(+), 20 deletions(-) rename .github/ISSUE_TEMPLATE/{bug_report.md => 1-bug.md} (98%) rename .github/ISSUE_TEMPLATE/{feature_request.md => 2-feature.md} (100%) create mode 100644 .github/ISSUE_TEMPLATE/3-docs.md create mode 100644 .github/ISSUE_TEMPLATE/4-change.md create mode 100644 docs/.overrides/partials/comments.html create mode 100644 docs/js/feedback.js diff --git a/.copier-answers.yml b/.copier-answers.yml index a2111625..90ce2e79 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: 1.1.2 +_commit: 1.1.4 _src_path: gh:mkdocstrings/handler-template author_email: dev@pawamoy.fr author_fullname: Timothée Mazzucotelli diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/1-bug.md similarity index 98% rename from .github/ISSUE_TEMPLATE/bug_report.md rename to .github/ISSUE_TEMPLATE/1-bug.md index ca545c26..0df6e967 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/1-bug.md @@ -53,7 +53,7 @@ PASTE TRACEBACK HERE python -m mkdocstrings_handlers.python.debug # | xclip -selection clipboard ``` -PASTE OUTPUT HERE +PASTE MARKDOWN OUTPUT HERE ### Additional context + +### Relevant code snippets + + +### Link to the relevant documentation section + diff --git a/.github/ISSUE_TEMPLATE/4-change.md b/.github/ISSUE_TEMPLATE/4-change.md new file mode 100644 index 00000000..dc9a8f17 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/4-change.md @@ -0,0 +1,18 @@ +--- +name: Change request +about: Suggest any other kind of change for this project. +title: "change: " +assignees: pawamoy +--- + +### Is your change request related to a problem? Please describe. + + +### Describe the solution you'd like + + +### Describe alternatives you've considered + + +### Additional context + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6af01962..bbc08404 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,13 +36,11 @@ Run `make help` to see all the available actions! ## Tasks -This project uses [duty](https://github.com/pawamoy/duty) to run tasks. -A Makefile is also provided. The Makefile will try to run certain tasks -on multiple Python versions. If for some reason you don't want to run the task -on multiple Python versions, you run the task directly with `make run duty TASK`. - -The Makefile detects if a virtual environment is activated, -so `make` will work the same with the virtualenv activated or not. +The entry-point to run commands and tasks is the `make` Python script, +located in the `scripts` directory. Try running `make` to show the available commands and tasks. +The *commands* do not need the Python dependencies to be installed, +while the *tasks* do. +The cross-platform tasks are written in Python, thanks to [duty](https://github.com/pawamoy/duty). If you work in VSCode, we provide [an action to configure VSCode](https://pawamoy.github.io/copier-uv/work/#vscode-setup) diff --git a/devdeps.txt b/devdeps.txt index c7bb98f5..e0afd7e2 100644 --- a/devdeps.txt +++ b/devdeps.txt @@ -4,7 +4,7 @@ editables>=0.5 # maintenance build>=1.2 git-changelog>=2.5 -twine>=5.1; python_version < '3.13' +twine>=5.0; python_version < '3.13' # ci duty>=1.4 diff --git a/docs/.overrides/main.html b/docs/.overrides/main.html index cf8adeb7..1e956857 100644 --- a/docs/.overrides/main.html +++ b/docs/.overrides/main.html @@ -2,17 +2,19 @@ {% block announce %} - Sponsorship - is now available! + Fund this project through + sponsorship {% include ".icons/octicons/heart-fill-16.svg" %} — - For updates follow @pawamoy on + Follow + @pawamoy on {% include ".icons/fontawesome/brands/mastodon.svg" %} Fosstodon + for updates {% endblock %} diff --git a/docs/.overrides/partials/comments.html b/docs/.overrides/partials/comments.html new file mode 100644 index 00000000..0dedc405 --- /dev/null +++ b/docs/.overrides/partials/comments.html @@ -0,0 +1,57 @@ + + + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 612c7a5e..8e6f2fb4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,6 @@ +--- +hide: +- feedback +--- + --8<-- "README.md" diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 123fe42d..3bc3aa56 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -99,6 +99,10 @@ with your GitHub account, visit [pawamoy's sponsor profile][github sponsor profi and complete a sponsorship of **$10 a month or more**. You can use your individual or organization GitHub account for sponsoring. +Sponsorships lower than $10 a month are also very much appreciated, and useful. +They won't grant you access to Insiders, but they will be counted towards reaching sponsorship goals. +*Every* sponsorship helps us implementing new features and releasing them to the public. + **Important**: If you're sponsoring **[@pawamoy][github sponsor profile]** through a GitHub organization, please send a short email to insiders@pawamoy.fr with the name of your diff --git a/docs/js/feedback.js b/docs/js/feedback.js new file mode 100644 index 00000000..f97321a5 --- /dev/null +++ b/docs/js/feedback.js @@ -0,0 +1,14 @@ +const feedback = document.forms.feedback; +feedback.hidden = false; + +feedback.addEventListener("submit", function(ev) { + ev.preventDefault(); + const commentElement = document.getElementById("feedback"); + commentElement.style.display = "block"; + feedback.firstElementChild.disabled = true; + const data = ev.submitter.getAttribute("data-md-value"); + const note = feedback.querySelector(".md-feedback__note [data-md-value='" + data + "']"); + if (note) { + note.hidden = false; + } +}) diff --git a/docs/license.md b/docs/license.md index a873d2b5..e81c0edf 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,3 +1,8 @@ +--- +hide: +- feedback +--- + # License ``` diff --git a/mkdocs.yml b/mkdocs.yml index 631fbab9..040ab89b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,6 +93,9 @@ extra_css: - css/mkdocstrings.css - css/insiders.css +extra_javascript: +- js/feedback.js + markdown_extensions: - abbr - attr_list @@ -192,3 +195,15 @@ extra: link: https://gitter.im/mkdocstrings/python - icon: fontawesome/brands/python link: https://pypi.org/project/mkdocstrings-python/ + analytics: + feedback: + title: Was this page helpful? + ratings: + - icon: material/emoticon-happy-outline + name: This page was helpful + data: 1 + note: Thanks for your feedback! + - icon: material/emoticon-sad-outline + name: This page could be improved + data: 0 + note: Let us know how we can improve this page. diff --git a/pyproject.toml b/pyproject.toml index 1fc5bb58..544dfffe 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,7 +50,19 @@ version = {source = "scm"} package-dir = "src" includes = ["src/mkdocstrings_handlers"] editable-backend = "editables" -source-includes = ["share"] +excludes = ["**/.pytest_cache"] +source-includes = [ + "config", + "docs", + "scripts", + "share", + "tests", + "devdeps.txt", + "duties.py", + "mkdocs.yml", + "*.md", + "LICENSE", +] [tool.pdm.build.wheel-data] data = [ diff --git a/scripts/make b/scripts/make index c097985e..d898022e 100755 --- a/scripts/make +++ b/scripts/make @@ -1,6 +1,8 @@ #!/usr/bin/env python3 """Management commands.""" +from __future__ import annotations + import os import shutil import subprocess @@ -15,9 +17,12 @@ exe = "" prefix = "" -def shell(cmd: str) -> None: +def shell(cmd: str, capture_output: bool = False, **kwargs: Any) -> str | None: """Run a shell command.""" - subprocess.run(cmd, shell=True, check=True) # noqa: S602 + if capture_output: + return subprocess.check_output(cmd, shell=True, text=True, **kwargs) # noqa: S602 + subprocess.run(cmd, shell=True, check=True, stderr=subprocess.STDOUT, **kwargs) # noqa: S602 + return None @contextmanager @@ -37,8 +42,8 @@ def uv_install() -> None: uv_opts = "" if "UV_RESOLUTION" in os.environ: uv_opts = f"--resolution={os.getenv('UV_RESOLUTION')}" - cmd = f"uv pip compile {uv_opts} pyproject.toml devdeps.txt | uv pip install -r -" - shell(cmd) + 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: @@ -199,5 +204,7 @@ def main() -> int: if __name__ == "__main__": try: sys.exit(main()) - except Exception: # noqa: BLE001 - sys.exit(1) + except subprocess.CalledProcessError as process: + if process.output: + print(process.output, file=sys.stderr) # noqa: T201 + sys.exit(process.returncode) From 41de4d14abf0ce7e0bc721a285d54f9a6ef0cdf0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 25 Jul 2024 18:17:25 +0200 Subject: [PATCH 006/134] chore: Prepare release 1.10.7 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 51d7d3cb..4b70d3ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 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.10.7](https://github.com/mkdocstrings/python/releases/tag/1.10.7) - 2024-07-25 + +[Compare with 1.10.6](https://github.com/mkdocstrings/python/compare/1.10.6...1.10.7) + +### Packaging + +- Include tests and all relevant files for downstream packaging in source distribution + ## [1.10.6](https://github.com/mkdocstrings/python/releases/tag/1.10.6) - 2024-07-25 [Compare with 1.10.5](https://github.com/mkdocstrings/python/compare/1.10.5...1.10.6) From a87dcad36065dc3171512e166ec632ee3e5b0a64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 14 Aug 2024 19:35:28 +0200 Subject: [PATCH 007/134] build: Depend on Griffe 0.49 --- pyproject.toml | 2 +- src/mkdocstrings_handlers/python/handler.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 544dfffe..fcc1022c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,7 +30,7 @@ classifiers = [ ] dependencies = [ "mkdocstrings>=0.25", - "griffe>=0.48", + "griffe>=0.49", ] [project.urls] diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index d7c39699..a4a5b47c 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -19,7 +19,7 @@ ModulesCollection, Parser, load_extensions, - patch_logger, + patch_loggers, ) from mkdocstrings.extension import PluginError from mkdocstrings.handlers.base import BaseHandler, CollectionError, CollectorItem @@ -50,7 +50,7 @@ def chdir(path: str) -> Iterator[None]: # noqa: D103 logger = get_logger(__name__) -patch_logger(get_logger) +patch_loggers(get_logger) class PythonHandler(BaseHandler): From a541b5bbe39ae6f9e6f8b5a56d45d5bdb979b735 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 14 Aug 2024 19:50:17 +0200 Subject: [PATCH 008/134] chore: Prepare release 1.10.8 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b70d3ee..13c080cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 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.10.8](https://github.com/mkdocstrings/python/releases/tag/1.10.8) - 2024-08-14 + +[Compare with 1.10.7](https://github.com/mkdocstrings/python/compare/1.10.7...1.10.8) + +### Build + +- Depend on Griffe 0.49 ([a87dcad](https://github.com/mkdocstrings/python/commit/a87dcad36065dc3171512e166ec632ee3e5b0a64) by Timothée Mazzucotelli). + ## [1.10.7](https://github.com/mkdocstrings/python/releases/tag/1.10.7) - 2024-07-25 [Compare with 1.10.6](https://github.com/mkdocstrings/python/compare/1.10.6...1.10.7) From 81d698e5073e6158b2e269c279ee546163fd6ce8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 30 Aug 2024 19:36:34 +0200 Subject: [PATCH 009/134] chore: Clean up check duty --- duties.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/duties.py b/duties.py index 56c54aa6..f1909cc1 100644 --- a/duties.py +++ b/duties.py @@ -53,8 +53,8 @@ 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_dependencies", "check-api"]) -def check(ctx: Context) -> None: # noqa: ARG001 +@duty(pre=["check_quality", "check_types", "check_docs", "check-api"]) +def check(ctx: Context) -> None: """Check it all!""" From 2299ab55641585d65babe0e116a6465b4736dcd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 30 Aug 2024 19:36:58 +0200 Subject: [PATCH 010/134] build: Explicitly depend on mkdocs-autorefs to be able to specify lower bound --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index fcc1022c..f1ff7334 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,6 +30,7 @@ classifiers = [ ] dependencies = [ "mkdocstrings>=0.25", + "mkdocs-autorefs>=1.0", "griffe>=0.49", ] From 68cb72f62253f54146ece621345b36c90d712913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 30 Aug 2024 19:55:02 +0200 Subject: [PATCH 011/134] refactor: Use new autorefs syntax --- docs/usage/configuration/docstrings.md | 12 ++++++------ docs/usage/configuration/general.md | 2 +- docs/usage/configuration/members.md | 12 ++++++------ src/mkdocstrings_handlers/python/rendering.py | 7 +++++-- .../material/_base/docstring/attributes.html.jinja | 6 +++--- .../material/_base/docstring/classes.html.jinja | 6 +++--- .../material/_base/docstring/functions.html.jinja | 6 +++--- .../material/_base/docstring/modules.html.jinja | 6 +++--- .../templates/material/_base/expression.html.jinja | 4 ++-- 9 files changed, 32 insertions(+), 29 deletions(-) diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index dcb35f5e..027ebaed 100644 --- a/docs/usage/configuration/docstrings.md +++ b/docs/usage/configuration/docstrings.md @@ -208,8 +208,8 @@ In that case, the Spacy tables can help. **Type** | **Name** | **Description** | **Default** ---------- | ----------- | ------------------------ | ----------- -list[int \| float] | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required* -VacuumType \| Literal["regular"] | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA` +list[int \| float] | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required* +VacuumType \| Literal["regular"] | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA` //// //// tab | List @@ -222,8 +222,8 @@ Lists work well whatever the length of names, type annotations, descriptions, et **Other Parameters:** -- `gravity_forces` (list[int \| float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. -- `vacuum_type` (VacuumType \| Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +- `gravity_forces` (list[int \| float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +- `vacuum_type` (VacuumType \| Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. //// //// tab | Spacy @@ -241,8 +241,8 @@ by reserving more horizontal space on the second column. **Name** | **Description** ----------- | --------------- -`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:** list[int \| float] DEFAULT: required -`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:**VacuumType \| Literal["regular"] DEFAULT: VacuumType.PLASMA +`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:** list[int \| float] DEFAULT: required +`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:**VacuumType \| Literal["regular"] DEFAULT: VacuumType.PLASMA //// /// diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index e4ddaec1..d8d7f250 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -139,7 +139,7 @@ def some_function(): ## `preload_modules` -- **:octicons-package-24: Type list[str] | None :material-equal: `None`{ title="default value" }** +- **:octicons-package-24: Type list[str] | None :material-equal: `None`{ title="default value" }** Pre-load modules that are not specified directly in [autodoc instructions][autodoc syntax] (`::: identifier`). diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index 1e5ff771..119d8294 100644 --- a/docs/usage/configuration/members.md +++ b/docs/usage/configuration/members.md @@ -2,8 +2,8 @@ ## `members` -- **:octicons-package-24: Type list[str] | - bool | None :material-equal: `None`{ title="default value" }** +- **:octicons-package-24: Type list[str] | + bool | None :material-equal: `None`{ title="default value" }** An explicit list of members to render. @@ -97,8 +97,8 @@ INFO: **The default behavior (with unspecified `members` or `members: null`) is ## `inherited_members` -- **:octicons-package-24: Type list[str] | - bool :material-equal: `False`{ title="default value" }** +- **:octicons-package-24: Type list[str] | + bool :material-equal: `False`{ title="default value" }** An explicit list of inherited members (for classes) to render. @@ -331,7 +331,7 @@ def function_c(): ## `filters` -- **:octicons-package-24: Type list[str] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** +- **:octicons-package-24: Type list[str] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** A list of filters applied to filter objects based on their name. @@ -555,7 +555,7 @@ package [: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 bool | dict[str, bool] :material-equal: `False`{ title="default value" }** +- **:octicons-package-24: Type bool | dict[str, bool] :material-equal: `False`{ title="default value" }** Whether to render summaries of modules, classes, functions (methods) and attributes. diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index b7fe3ad6..d5a88699 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -295,7 +295,10 @@ def do_crossref(path: str, *, brief: bool = True) -> Markup: full_path = path if brief: path = full_path.split(".")[-1] - return Markup("{path}").format(full_path=full_path, path=path) + return Markup("{path}").format( + full_path=full_path, + path=path, + ) @lru_cache @@ -327,7 +330,7 @@ def repl(match: Match) -> str: path = match.group() path_var = f"path{group_number}" variables[path_var] = path - return f"{{{path_var}}}" + return f"{{{path_var}}}" text = re.sub(r"([\w.]+)", repl, text) if code: diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja index 396e36dd..34aa0119 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja @@ -33,7 +33,7 @@ Context: {% for attribute in section.value %} - {{ attribute.name }} + {{ attribute.name }} {% if attribute.annotation %} {% with expression = attribute.annotation %} @@ -58,7 +58,7 @@ Context: