diff --git a/scripts/griffe_extensions.py b/scripts/griffe_extensions.py
index eb50f5f2..6931c8a5 100644
--- a/scripts/griffe_extensions.py
+++ b/scripts/griffe_extensions.py
@@ -13,6 +13,8 @@
class CustomFields(griffe.Extension):
"""Support our custom dataclass fields."""
+ _custom_field_path = "mkdocstrings_handlers.python._internal.config._Field"
+
def on_attribute_instance(
self,
*,
@@ -24,11 +26,11 @@ def on_attribute_instance(
if attr.docstring:
return
try:
- field: griffe.ExprCall = attr.annotation.slice.elements[1] # type: ignore[union-attr]
+ field = attr.annotation.slice.elements[1] # type: ignore[union-attr]
except AttributeError:
return
- if field.canonical_path == "mkdocstrings_handlers.python._internal.config._Field":
+ if isinstance(field, griffe.ExprCall) and field.canonical_path == self._custom_field_path:
description = next(
attr.value
for attr in field.arguments
diff --git a/src/mkdocstrings_handlers/python/__init__.py b/src/mkdocstrings_handlers/python/__init__.py
index faa9b9f4..a073e783 100644
--- a/src/mkdocstrings_handlers/python/__init__.py
+++ b/src/mkdocstrings_handlers/python/__init__.py
@@ -1,17 +1,22 @@
"""Python handler for mkdocstrings."""
from mkdocstrings_handlers.python._internal.config import (
+ UNSET,
AutoStyleOptions,
+ ChainedOptions,
GoogleStyleOptions,
Inventory,
+ MembersOption,
NumpyStyleOptions,
PerStyleOptions,
PythonConfig,
PythonInputConfig,
PythonInputOptions,
PythonOptions,
+ RecursiveOptions,
SphinxStyleOptions,
SummaryOption,
+ Unset,
)
from mkdocstrings_handlers.python._internal.handler import PythonHandler, get_handler
from mkdocstrings_handlers.python._internal.rendering import (
@@ -23,23 +28,24 @@
do_as_functions_section,
do_as_modules_section,
do_backlink_tree,
- do_crossref,
do_filter_objects,
do_format_attribute,
do_format_code,
do_format_signature,
do_get_template,
- do_multi_crossref,
do_order_members,
do_split_path,
do_stash_crossref,
)
__all__ = [
+ "UNSET",
"AutoStyleOptions",
"AutorefsHook",
+ "ChainedOptions",
"GoogleStyleOptions",
"Inventory",
+ "MembersOption",
"NumpyStyleOptions",
"Order",
"PerStyleOptions",
@@ -48,21 +54,21 @@
"PythonInputConfig",
"PythonInputOptions",
"PythonOptions",
+ "RecursiveOptions",
"SphinxStyleOptions",
"SummaryOption",
"Tree",
+ "Unset",
"do_as_attributes_section",
"do_as_classes_section",
"do_as_functions_section",
"do_as_modules_section",
"do_backlink_tree",
- "do_crossref",
"do_filter_objects",
"do_format_attribute",
"do_format_code",
"do_format_signature",
"do_get_template",
- "do_multi_crossref",
"do_order_members",
"do_split_path",
"do_stash_crossref",
diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py
index 210f8fe2..562284e4 100644
--- a/src/mkdocstrings_handlers/python/_internal/config.py
+++ b/src/mkdocstrings_handlers/python/_internal/config.py
@@ -1,10 +1,55 @@
# Configuration and options dataclasses.
+#
+# We start by declaring a custom field function that will help us generate a JSON schema
+# where each item links to the relevant documentation page and section.
+# The function is a no-op when Pydantic is not available.
+#
+# Then we define the dataclasses for specific, complex options (more than just a built-in type),
+# like `SummaryOption`, and `MembersOption`.
+#
+# Finally, we define the complete options dataclasses, one for the inputs matching what users
+# write in mkdocs.yml, and one for the coerced options, which is used in the Jinja templates.
+# The dataclasses are split into inputs and "coerced" because we want to expose a JSON schema
+# corresponding to the inputs only, but we still want to validate and transform the inputs
+# into something more convenient for templates.
+#
+# We also define the input configuration and final configuration dataclasses.
+# Similarly to the options dataclasses, they are split into inputs and "coerced",
+# for the JSON schema and convenience in templates, respectively.
+# Options correspond to the items under `plugins[mkdocstrings].handlers.python.options`,
+# while configuration corresponds to the items under `plugins[mkdocstrings].handlers.python` (including options).
+#
+# ---
+#
+# NOTE: **Note about fine-grain configuration.** To allow repeating a subset of options under `members`,
+# we define this subset of options into `RecursiveOptions`, which `PythonInputOptions` inherits from.
+# This allows us to reference `RecursiveOptions` in the `members` option.
+#
+# ---
+#
+# NOTE: **Note about defaults and merging options.** One thing I (@pawamoy) am not satisfied with
+# is how we handle default values and how we merge options. For the context:
+#
+# - Options can be defined globally (in `mkdocs.yml`), locally (under each `:::` injection),
+# and recursively (under `members` options).
+# - We want to merge the members options into the local options, into the global options,
+# into the default options.
+# - But since dataclasses are total, if we merge one instance into the other, it will override
+# all the unspecified options of the merged instance into the other instance.
+# It means the receiving/new instance will have all the other fields reset to default values.
+# - To avoid this, we keep track of the inputs (dictionaries) used to instantiate dataclasses,
+# so that we can merge the inputs instead, which are partial, and then instantiate
+# the new dataclass with the merged inputs.
+# - That makes a lot of back and forth between dataclasses and dictionaries,
+# which is not very efficient or elegant.
+# See `ChainedOptions.chain()` and `PythonHandler.get_options()`.
from __future__ import annotations
import re
import sys
from dataclasses import field, fields
+from functools import cached_property
from typing import TYPE_CHECKING, Annotated, Any, Literal
from mkdocstrings import get_logger
@@ -17,7 +62,6 @@
else:
from typing_extensions import Self
-
_logger = get_logger(__name__)
_DEFAULT_FILTERS = ["!^_[^_]"]
@@ -84,7 +128,7 @@ def _Field(*args: Any, **kwargs: Any) -> None: # type: ignore[misc] # noqa: N8
if TYPE_CHECKING:
- from collections.abc import MutableMapping
+ from collections.abc import Mapping, MutableMapping
# YORE: EOL 3.9: Remove block.
@@ -93,6 +137,65 @@ def _Field(*args: Any, **kwargs: Any) -> None: # type: ignore[misc] # noqa: N8
_dataclass_options["kw_only"] = True
+# --------------------------------------------------------------------------- #
+# Chainable dataclass. #
+# --------------------------------------------------------------------------- #
+@dataclass
+class Unset:
+ """Unset value."""
+
+ def __bool__(self) -> bool:
+ """Always false."""
+ return False
+
+ def __repr__(self) -> str:
+ return "UNSET"
+
+
+UNSET = Unset()
+"""Unset value."""
+
+
+class ChainedOptions:
+ """Chained options."""
+
+ def __init__(self, *dataclasses: ChainedOptions | PythonOptions, unset: Any = UNSET) -> None:
+ self._dataclasses: tuple[ChainedOptions | PythonOptions, ...] = tuple(dataclasses)
+ self._unset = unset
+
+ def __getattr__(self, name: str) -> Any:
+ """Get the attribute from the dataclass."""
+ for dataclass in reversed(self._dataclasses):
+ if (value := getattr(dataclass, name)) is not self._unset:
+ return value
+ return self._unset
+
+ @cached_property
+ def extra(self) -> dict[str, Any]:
+ """Get the extra options from the dataclass."""
+ # Special case for `extra` because we want to merge all extra options.
+ extra = {}
+ for dataclass in self._dataclasses:
+ if isinstance(dataclass.extra, dict):
+ extra.update(dataclass.extra)
+ return extra
+
+ def chain(self, *options: Mapping[str, Any] | PythonOptions | Any) -> ChainedOptions:
+ """Chain the current options with the given options."""
+ return ChainedOptions(
+ self,
+ *(
+ opts
+ if isinstance(opts, PythonOptions)
+ else PythonOptions.from_data(**(opts if isinstance(opts, dict) else {}))
+ for opts in options
+ ),
+ )
+
+
+# --------------------------------------------------------------------------- #
+# Complex options. #
+# --------------------------------------------------------------------------- #
# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
@dataclass(**_dataclass_options) # type: ignore[call-overload]
class GoogleStyleOptions:
@@ -361,29 +464,79 @@ class SummaryOption:
] = False
+# --------------------------------------------------------------------------- #
+# Complex configuration items. #
+# --------------------------------------------------------------------------- #
# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
@dataclass(**_dataclass_options) # type: ignore[call-overload]
-class PythonInputOptions:
- """Accepted input options."""
+class Inventory:
+ """An inventory."""
- allow_inspection: Annotated[
- bool,
+ url: Annotated[
+ str,
_Field(
- group="general",
- description="Whether to allow inspecting modules when visiting them is not possible.",
+ parent="inventories",
+ description="The URL of the inventory.",
),
- ] = True
+ ]
- force_inspection: Annotated[
- bool,
+ base_url: Annotated[
+ str | None,
_Field(
- group="general",
- description="Whether to force using dynamic analysis when loading data.",
+ parent="inventories",
+ description="The base URL of the inventory.",
),
- ] = False
+ ] = None
+
+ domains: Annotated[
+ list[str],
+ _Field(
+ parent="inventories",
+ description="The domains to load from the inventory.",
+ ),
+ ] = field(default_factory=lambda: ["py"])
+
+ @property
+ def _config(self) -> dict[str, Any]:
+ return {"base_url": self.base_url, "domains": self.domains}
+
+
+# --------------------------------------------------------------------------- #
+# Special "recursive options" dataclasses (for fine-grain configuration). #
+# --------------------------------------------------------------------------- #
+# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
+@dataclass(**_dataclass_options) # type: ignore[call-overload]
+class MembersOption:
+ """Members option."""
+
+ # YORE: EOL 3.9: Replace ` = ""` with `` within block.
+ name: Annotated[
+ str,
+ _Field(
+ group="members",
+ parent="members",
+ description="Name of the member to render.",
+ min_length=1,
+ ),
+ ] = ""
+
+ options: Annotated[
+ dict[str, Any] | RecursiveOptions | None,
+ _Field(
+ group="members",
+ parent="members",
+ description="Rendering options for this specific member.",
+ ),
+ ] = None
+
+
+# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
+@dataclass(**_dataclass_options) # type: ignore[call-overload]
+class RecursiveOptions:
+ """Options that can be applied to the current object and any of its selected members."""
annotations_path: Annotated[
- Literal["brief", "source", "full"],
+ Literal["brief", "source", "full"] | Unset,
_Field(
group="signatures",
description="The verbosity for annotations path: `brief` (recommended), `source` (as written in the source), or `full`.",
@@ -391,50 +544,23 @@ class PythonInputOptions:
] = "brief"
backlinks: Annotated[
- Literal["flat", "tree", False],
+ Literal["flat", "tree", False] | Unset,
_Field(
group="general",
description="Whether to render backlinks, and how.",
),
] = False
- docstring_options: Annotated[
- GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None,
- _Field(
- group="docstrings",
- description="""The options for the docstring parser.
-
- See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs.
- """,
- ),
- ] = None
-
docstring_section_style: Annotated[
- Literal["table", "list", "spacy"],
+ Literal["table", "list", "spacy"] | Unset,
_Field(
group="docstrings",
description="The style used to render docstring sections.",
),
] = "table"
- docstring_style: Annotated[
- Literal["auto", "google", "numpy", "sphinx"] | None,
- _Field(
- group="docstrings",
- description="The docstring style to use: `auto`, `google`, `numpy`, `sphinx`, or `None`.",
- ),
- ] = "google"
-
- extensions: Annotated[
- list[str | dict[str, Any]],
- _Field(
- group="general",
- description="A list of Griffe extensions to load.",
- ),
- ] = field(default_factory=list)
-
filters: Annotated[
- list[str] | Literal["public"],
+ list[str] | Literal["public"] | Unset,
_Field(
group="members",
description="""A list of filters, or `"public"`.
@@ -456,16 +582,8 @@ class PythonInputOptions:
),
] = field(default_factory=lambda: _DEFAULT_FILTERS.copy())
- find_stubs_package: Annotated[
- bool,
- _Field(
- group="general",
- description="Whether to load stubs package (package-stubs) when extracting docstrings.",
- ),
- ] = False
-
group_by_category: Annotated[
- bool,
+ bool | Unset,
_Field(
group="members",
description="Group the object's children by categories: attributes, classes, functions, and modules.",
@@ -473,23 +591,15 @@ class PythonInputOptions:
] = True
heading: Annotated[
- str,
+ str | Unset,
_Field(
group="headings",
description="A custom string to override the autogenerated heading of the root object.",
),
] = ""
- heading_level: Annotated[
- int,
- _Field(
- group="headings",
- description="The initial heading level to use.",
- ),
- ] = 2
-
inherited_members: Annotated[
- bool | list[str],
+ bool | list[str] | Unset,
_Field(
group="members",
description="""A boolean, or an explicit list of inherited members to render.
@@ -501,7 +611,7 @@ class PythonInputOptions:
] = False
line_length: Annotated[
- int,
+ int | Unset,
_Field(
group="signatures",
description="Maximum line length when formatting code/signatures.",
@@ -509,7 +619,7 @@ class PythonInputOptions:
] = 60
members: Annotated[
- list[str] | bool | None,
+ list[str | MembersOption] | bool | None | Unset,
_Field(
group="members",
description="""A boolean, or an explicit list of members to render.
@@ -522,7 +632,7 @@ class PythonInputOptions:
] = None
members_order: Annotated[
- Order | list[Order],
+ Order | list[Order] | Unset,
_Field(
group="members",
description="""The members ordering to use.
@@ -539,7 +649,7 @@ class PythonInputOptions:
] = "alphabetical"
merge_init_into_class: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to merge the `__init__` method into the class' signature and docstring.",
@@ -547,7 +657,7 @@ class PythonInputOptions:
] = False
modernize_annotations: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="Whether to modernize annotations, for example `Optional[str]` into `str | None`.",
@@ -555,32 +665,15 @@ class PythonInputOptions:
] = False
parameter_headings: Annotated[
- bool,
+ bool | Unset,
_Field(
group="headings",
description="Whether to render headings for parameters (therefore showing parameters in the ToC).",
),
] = False
- preload_modules: Annotated[
- list[str],
- _Field(
- group="general",
- description="""Pre-load modules that are not specified directly in autodoc instructions (`::: identifier`).
-
- It is useful when you want to render documentation for a particular member of an object,
- and this member is imported from another package than its parent.
-
- For an imported member to be rendered, you need to add it to the `__all__` attribute
- of the importing module.
-
- The modules must be listed as an array of strings.
- """,
- ),
- ] = field(default_factory=list)
-
relative_crossrefs: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to enable the relative crossref syntax.",
@@ -588,7 +681,7 @@ class PythonInputOptions:
] = False
scoped_crossrefs: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to enable the scoped crossref ability.",
@@ -596,7 +689,7 @@ class PythonInputOptions:
] = False
show_overloads: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="Show the overloads of a function or method.",
@@ -604,7 +697,7 @@ class PythonInputOptions:
] = True
separate_signature: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="""Whether to put the whole signature in a code block below the heading.
@@ -615,7 +708,7 @@ class PythonInputOptions:
] = False
show_bases: Annotated[
- bool,
+ bool | Unset,
_Field(
group="general",
description="Show the base classes of a class.",
@@ -623,7 +716,7 @@ class PythonInputOptions:
] = True
show_category_heading: Annotated[
- bool,
+ bool | Unset,
_Field(
group="headings",
description="When grouped by categories, show a heading for each category.",
@@ -631,7 +724,7 @@ class PythonInputOptions:
] = False
show_docstring_attributes: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Attributes' section in the object's docstring.",
@@ -639,7 +732,7 @@ class PythonInputOptions:
] = True
show_docstring_classes: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Classes' section in the object's docstring.",
@@ -647,7 +740,7 @@ class PythonInputOptions:
] = True
show_docstring_description: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the textual block (including admonitions) in the object's docstring.",
@@ -655,7 +748,7 @@ class PythonInputOptions:
] = True
show_docstring_examples: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Examples' section in the object's docstring.",
@@ -663,7 +756,7 @@ class PythonInputOptions:
] = True
show_docstring_functions: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Functions' or 'Methods' sections in the object's docstring.",
@@ -671,7 +764,7 @@ class PythonInputOptions:
] = True
show_docstring_modules: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Modules' section in the object's docstring.",
@@ -679,7 +772,7 @@ class PythonInputOptions:
] = True
show_docstring_other_parameters: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Other Parameters' section in the object's docstring.",
@@ -687,7 +780,7 @@ class PythonInputOptions:
] = True
show_docstring_parameters: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Parameters' section in the object's docstring.",
@@ -695,7 +788,7 @@ class PythonInputOptions:
] = True
show_docstring_raises: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Raises' section in the object's docstring.",
@@ -703,7 +796,7 @@ class PythonInputOptions:
] = True
show_docstring_receives: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Receives' section in the object's docstring.",
@@ -711,7 +804,7 @@ class PythonInputOptions:
] = True
show_docstring_returns: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Returns' section in the object's docstring.",
@@ -719,7 +812,7 @@ class PythonInputOptions:
] = True
show_docstring_warns: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Warns' section in the object's docstring.",
@@ -727,7 +820,7 @@ class PythonInputOptions:
] = True
show_docstring_yields: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to display the 'Yields' section in the object's docstring.",
@@ -735,7 +828,7 @@ class PythonInputOptions:
] = True
show_if_no_docstring: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Show the object heading even if it has no docstring or children with docstrings.",
@@ -743,7 +836,7 @@ class PythonInputOptions:
] = False
show_inheritance_diagram: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Show the inheritance diagram of a class using Mermaid.",
@@ -751,7 +844,7 @@ class PythonInputOptions:
] = False
show_labels: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Whether to show labels of the members.",
@@ -759,50 +852,15 @@ class PythonInputOptions:
] = True
show_object_full_path: Annotated[
- bool,
+ bool | Unset,
_Field(
group="docstrings",
description="Show the full Python path of every object.",
),
] = False
- show_root_full_path: Annotated[
- bool,
- _Field(
- group="docstrings",
- description="Show the full Python path for the root object heading.",
- ),
- ] = True
-
- show_root_heading: Annotated[
- bool,
- _Field(
- group="headings",
- description="""Show the heading of the object at the root of the documentation tree.
-
- The root object is the object referenced by the identifier after `:::`.
- """,
- ),
- ] = False
-
- show_root_members_full_path: Annotated[
- bool,
- _Field(
- group="headings",
- description="Show the full Python path of the root members.",
- ),
- ] = False
-
- show_root_toc_entry: Annotated[
- bool,
- _Field(
- group="headings",
- description="If the root heading is not shown, at least add a ToC entry for it.",
- ),
- ] = True
-
show_signature_annotations: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="Show the type annotations in methods and functions signatures.",
@@ -810,7 +868,7 @@ class PythonInputOptions:
] = False
show_signature: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="Show methods and functions signatures.",
@@ -818,7 +876,7 @@ class PythonInputOptions:
] = True
show_source: Annotated[
- bool,
+ bool | Unset,
_Field(
group="general",
description="Show the source code of this object.",
@@ -826,7 +884,7 @@ class PythonInputOptions:
] = True
show_submodules: Annotated[
- bool,
+ bool | Unset,
_Field(
group="members",
description="When rendering a module, show its submodules recursively.",
@@ -834,7 +892,7 @@ class PythonInputOptions:
] = False
show_symbol_type_heading: Annotated[
- bool,
+ bool | Unset,
_Field(
group="headings",
description="Show the symbol type in headings (e.g. mod, class, meth, func and attr).",
@@ -842,7 +900,7 @@ class PythonInputOptions:
] = False
show_symbol_type_toc: Annotated[
- bool,
+ bool | Unset,
_Field(
group="headings",
description="Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).",
@@ -850,7 +908,7 @@ class PythonInputOptions:
] = False
signature_crossrefs: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="Whether to render cross-references for type annotations in signatures.",
@@ -858,7 +916,7 @@ class PythonInputOptions:
] = False
summary: Annotated[
- bool | SummaryOption,
+ bool | SummaryOption | Unset,
_Field(
group="members",
description="Whether to render summaries of modules, classes, functions (methods) and attributes.",
@@ -866,7 +924,7 @@ class PythonInputOptions:
] = field(default_factory=SummaryOption)
toc_label: Annotated[
- str,
+ str | Unset,
_Field(
group="headings",
description="A custom string to override the autogenerated toc label of the root object.",
@@ -874,15 +932,135 @@ class PythonInputOptions:
] = ""
unwrap_annotated: Annotated[
- bool,
+ bool | Unset,
_Field(
group="signatures",
description="Whether to unwrap `Annotated` types to show only the type without the annotations.",
),
] = False
+
+# --------------------------------------------------------------------------- #
+# Input dataclasses (untransformed data, loaded from `mkdocs.yml`). #
+# --------------------------------------------------------------------------- #
+# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
+@dataclass(**_dataclass_options) # type: ignore[call-overload]
+class PythonInputOptions(RecursiveOptions):
+ """Accepted input options."""
+
+ allow_inspection: Annotated[
+ bool | Unset,
+ _Field(
+ group="general",
+ description="Whether to allow inspecting modules when visiting them is not possible.",
+ ),
+ ] = True
+
+ force_inspection: Annotated[
+ bool | Unset,
+ _Field(
+ group="general",
+ description="Whether to force using dynamic analysis when loading data.",
+ ),
+ ] = False
+
+ docstring_options: Annotated[
+ GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None | Unset,
+ _Field(
+ group="docstrings",
+ description="""The options for the docstring parser.
+
+ See [docstring parsers](https://mkdocstrings.github.io/griffe/reference/docstrings/) and their options in Griffe docs.
+ """,
+ ),
+ ] = None
+
+ docstring_style: Annotated[
+ Literal["auto", "google", "numpy", "sphinx"] | None | Unset,
+ _Field(
+ group="docstrings",
+ description="The docstring style to use: `auto`, `google`, `numpy`, `sphinx`, or `None`.",
+ ),
+ ] = "google"
+
+ extensions: Annotated[
+ list[str | dict[str, Any]] | Unset,
+ _Field(
+ group="general",
+ description="A list of Griffe extensions to load.",
+ ),
+ ] = field(default_factory=list)
+
+ find_stubs_package: Annotated[
+ bool | Unset,
+ _Field(
+ group="general",
+ description="Whether to load stubs package (package-stubs) when extracting docstrings.",
+ ),
+ ] = False
+
+ heading_level: Annotated[
+ int | Unset,
+ _Field(
+ group="headings",
+ description="The initial heading level to use.",
+ ),
+ ] = 2
+
+ preload_modules: Annotated[
+ list[str] | Unset,
+ _Field(
+ group="general",
+ description="""Pre-load modules that are not specified directly in autodoc instructions (`::: identifier`).
+
+ It is useful when you want to render documentation for a particular member of an object,
+ and this member is imported from another package than its parent.
+
+ For an imported member to be rendered, you need to add it to the `__all__` attribute
+ of the importing module.
+
+ The modules must be listed as an array of strings.
+ """,
+ ),
+ ] = field(default_factory=list)
+
+ show_root_full_path: Annotated[
+ bool | Unset,
+ _Field(
+ group="docstrings",
+ description="Show the full Python path for the root object heading.",
+ ),
+ ] = True
+
+ show_root_heading: Annotated[
+ bool | Unset,
+ _Field(
+ group="headings",
+ description="""Show the heading of the object at the root of the documentation tree.
+
+ The root object is the object referenced by the identifier after `:::`.
+ """,
+ ),
+ ] = False
+
+ show_root_members_full_path: Annotated[
+ bool | Unset,
+ _Field(
+ group="headings",
+ description="Show the full Python path of the root members.",
+ ),
+ ] = False
+
+ show_root_toc_entry: Annotated[
+ bool | Unset,
+ _Field(
+ group="headings",
+ description="If the root heading is not shown, at least add a ToC entry for it.",
+ ),
+ ] = True
+
extra: Annotated[
- dict[str, Any],
+ dict[str, Any] | Unset,
_Field(
group="general",
description="Extra options.",
@@ -925,71 +1103,9 @@ def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
@classmethod
def from_data(cls, **data: Any) -> Self:
"""Create an instance from a dictionary."""
- return cls(**cls.coerce(**data))
-
-
-# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
-@dataclass(**_dataclass_options) # type: ignore[call-overload]
-class PythonOptions(PythonInputOptions): # type: ignore[override,unused-ignore]
- """Final options passed as template context."""
-
- filters: list[tuple[re.Pattern, bool]] | Literal["public"] = field( # type: ignore[assignment]
- default_factory=lambda: [
- (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in _DEFAULT_FILTERS
- ],
- )
- """A list of filters, or `"public"`."""
-
- summary: SummaryOption = field(default_factory=SummaryOption)
- """Whether to render summaries of modules, classes, functions (methods) and attributes."""
-
- @classmethod
- def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
- """Create an instance from a dictionary."""
- if "filters" in data:
- # Non-insiders: transform back to default filters.
- # Next: `if "filters" in data and not isinstance(data["filters"], str):`.
- if data["filters"] == "public":
- data["filters"] = _DEFAULT_FILTERS
- # Filters are `None` or a sequence of strings (tests use tuples).
- data["filters"] = [
- (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in data["filters"] or ()
- ]
- return super().coerce(**data)
-
-
-# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
-@dataclass(**_dataclass_options) # type: ignore[call-overload]
-class Inventory:
- """An inventory."""
-
- url: Annotated[
- str,
- _Field(
- parent="inventories",
- description="The URL of the inventory.",
- ),
- ]
-
- base_url: Annotated[
- str | None,
- _Field(
- parent="inventories",
- description="The base URL of the inventory.",
- ),
- ] = None
-
- domains: Annotated[
- list[str],
- _Field(
- parent="inventories",
- description="The domains to load from the inventory.",
- ),
- ] = field(default_factory=lambda: ["py"])
-
- @property
- def _config(self) -> dict[str, Any]:
- return {"base_url": self.base_url, "domains": self.domains}
+ non_propagated_fields = {"heading", "members", "toc_label"}
+ unset_fields = {field.name for field in fields(cls)} - set(data) - non_propagated_fields
+ return cls(**cls.coerce(**data), **dict.fromkeys(unset_fields, UNSET))
# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
@@ -1033,6 +1149,43 @@ def from_data(cls, **data: Any) -> Self:
return cls(**cls.coerce(**data))
+# --------------------------------------------------------------------------- #
+# Final dataclasses (transformed data, used in templates). #
+# --------------------------------------------------------------------------- #
+# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
+@dataclass(**_dataclass_options) # type: ignore[call-overload]
+class PythonOptions(PythonInputOptions): # type: ignore[override,unused-ignore]
+ """Final options passed as template context."""
+
+ filters: list[tuple[re.Pattern, bool]] | Literal["public"] | Unset = field( # type: ignore[assignment]
+ default_factory=lambda: [
+ (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in _DEFAULT_FILTERS
+ ],
+ )
+ """A list of filters, or `"public"`."""
+
+ summary: SummaryOption | Unset = field(default_factory=SummaryOption)
+ """Whether to render summaries of modules, classes, functions (methods) and attributes."""
+
+ @classmethod
+ def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
+ """Create an instance from a dictionary."""
+ if "filters" in data:
+ # Non-insiders: transform back to default filters.
+ # Next: `if "filters" in data and not isinstance(data["filters"], str):`.
+ if data["filters"] == "public":
+ data["filters"] = _DEFAULT_FILTERS
+ # Filters are `None` or a sequence of strings (tests use tuples).
+ data["filters"] = [
+ (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in data["filters"] or ()
+ ]
+ return super().coerce(**data)
+
+ def chain(self, *options: Mapping[str, Any] | PythonOptions) -> ChainedOptions:
+ """Chain the current options with the given options."""
+ return ChainedOptions(self).chain(*options)
+
+
# YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
@dataclass(**_dataclass_options) # type: ignore[call-overload]
class PythonConfig(PythonInputConfig): # type: ignore[override,unused-ignore]
@@ -1044,9 +1197,9 @@ class PythonConfig(PythonInputConfig): # type: ignore[override,unused-ignore]
] = field(default_factory=list) # type: ignore[assignment]
options: Annotated[
- dict[str, Any],
+ PythonOptions,
_Field(description="Configuration options for collecting and rendering objects."),
- ] = field(default_factory=dict) # type: ignore[assignment]
+ ] = field(default_factory=PythonOptions)
@classmethod
def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
@@ -1055,4 +1208,6 @@ def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
data["inventories"] = [
Inventory(url=inv) if isinstance(inv, str) else Inventory(**inv) for inv in data["inventories"]
]
+ if "options" in data and isinstance(data["options"], dict):
+ data["options"] = PythonOptions.from_data(**data["options"])
return data
diff --git a/src/mkdocstrings_handlers/python/_internal/handler.py b/src/mkdocstrings_handlers/python/_internal/handler.py
index 158d7ddc..4425e3e5 100644
--- a/src/mkdocstrings_handlers/python/_internal/handler.py
+++ b/src/mkdocstrings_handlers/python/_internal/handler.py
@@ -54,17 +54,6 @@ def chdir(path: str) -> Iterator[None]:
patch_loggers(get_logger)
-# YORE: Bump 2: Remove block.
-def _warn_extra_options(names: Sequence[str]) -> None:
- warn(
- "Passing extra options directly under `options` is deprecated. "
- "Instead, pass them under `options.extra`, and update your templates. "
- f"Current extra (unrecognized) options: {', '.join(sorted(names))}",
- DeprecationWarning,
- stacklevel=3,
- )
-
-
class PythonHandler(BaseHandler):
"""The Python handler class."""
@@ -95,17 +84,11 @@ def __init__(self, config: PythonConfig, base_dir: Path, **kwargs: Any) -> None:
self.base_dir = base_dir
"""The base directory of the project."""
- # YORE: Bump 2: Remove block.
- global_extra, global_options = PythonOptions._extract_extra(config.options)
- if global_extra:
- _warn_extra_options(global_extra.keys()) # type: ignore[arg-type]
- self._global_extra = global_extra
- self.global_options = global_options
- """The global configuration options (in `mkdocs.yml`)."""
+ self.default_options = PythonOptions()
+ """The default configuration options."""
- # YORE: Bump 2: Replace `# ` with `` within block.
- # self.global_options = config.options
- # """The global configuration options (in `mkdocs.yml`)."""
+ self.global_options = config.options
+ """The global configuration options (in `mkdocs.yml`)."""
# Warn if user overrides base templates.
if self.custom_templates:
@@ -186,25 +169,11 @@ def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
Returns:
The combined options.
"""
- # YORE: Bump 2: Remove block.
- local_extra, local_options = PythonOptions._extract_extra(local_options) # type: ignore[arg-type]
- if local_extra:
- _warn_extra_options(local_extra.keys()) # type: ignore[arg-type]
- unknown_extra = self._global_extra | local_extra
-
- extra = {**self.global_options.get("extra", {}), **local_options.get("extra", {})}
- options = {**self.global_options, **local_options, "extra": extra}
try:
- # YORE: Bump 2: Replace `opts =` with `return` within line.
- opts = PythonOptions.from_data(**options)
+ return self.default_options.chain(self.global_options).chain(local_options)
except Exception as error:
raise PluginError(f"Invalid options: {error}") from error
- # YORE: Bump 2: Remove block.
- for key, value in unknown_extra.items():
- object.__setattr__(opts, key, value)
- return opts
-
def collect(self, identifier: str, options: PythonOptions) -> CollectorItem:
"""Collect the documentation for the given identifier.
@@ -229,29 +198,29 @@ def collect(self, identifier: str, options: PythonOptions) -> CollectorItem:
parser_options = options.docstring_options and asdict(options.docstring_options)
if unknown_module:
- extensions = self.normalize_extension_paths(options.extensions)
+ extensions = self.normalize_extension_paths(options.extensions) # type: ignore[arg-type]
loader = GriffeLoader(
extensions=load_extensions(*extensions),
search_paths=self._paths,
- docstring_parser=parser,
+ docstring_parser=parser, # type: ignore[arg-type]
docstring_options=parser_options, # type: ignore[arg-type]
modules_collection=self._modules_collection,
lines_collection=self._lines_collection,
- allow_inspection=options.allow_inspection,
- force_inspection=options.force_inspection,
+ allow_inspection=options.allow_inspection, # type: ignore[arg-type]
+ force_inspection=options.force_inspection, # type: ignore[arg-type]
)
try:
- for pre_loaded_module in options.preload_modules:
+ for pre_loaded_module in options.preload_modules: # type: ignore[union-attr]
if pre_loaded_module not in self._modules_collection:
loader.load(
pre_loaded_module,
try_relative_path=False,
- find_stubs_package=options.find_stubs_package,
+ find_stubs_package=options.find_stubs_package, # type: ignore[arg-type]
)
loader.load(
module_name,
try_relative_path=False,
- find_stubs_package=options.find_stubs_package,
+ find_stubs_package=options.find_stubs_package, # type: ignore[arg-type]
)
except ImportError as error:
raise CollectionError(str(error)) from error
@@ -288,7 +257,7 @@ def render(self, data: CollectorItem, options: PythonOptions) -> str:
Returns:
The rendered data (HTML).
"""
- template_name = rendering.do_get_template(self.env, data)
+ template_name = rendering.do_get_template(data)
template = self.env.get_template(template_name)
return template.render(
@@ -314,8 +283,6 @@ def update_env(self, config: Any) -> None: # noqa: ARG002
self.env.lstrip_blocks = True
self.env.keep_trailing_newline = False
self.env.filters["split_path"] = rendering.do_split_path
- self.env.filters["crossref"] = rendering.do_crossref
- self.env.filters["multi_crossref"] = rendering.do_multi_crossref
self.env.filters["order_members"] = rendering.do_order_members
self.env.filters["format_code"] = rendering.do_format_code
self.env.filters["format_signature"] = rendering.do_format_signature
diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py
index 897b6572..1059aa21 100644
--- a/src/mkdocstrings_handlers/python/_internal/rendering.py
+++ b/src/mkdocstrings_handlers/python/_internal/rendering.py
@@ -7,13 +7,11 @@
import string
import subprocess
import sys
-import warnings
from collections import defaultdict
from contextlib import suppress
from dataclasses import replace
from functools import lru_cache
-from pathlib import Path
-from re import Match, Pattern
+from re import Pattern
from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal, TypeVar
from griffe import (
@@ -30,7 +28,7 @@
DocstringSectionModules,
Object,
)
-from jinja2 import TemplateNotFound, pass_context, pass_environment
+from jinja2 import pass_context
from markupsafe import Markup
from mkdocs_autorefs import AutorefsHookInterface, Backlink, BacklinkCrumb
from mkdocstrings import get_logger
@@ -39,7 +37,6 @@
from collections.abc import Iterable, Iterator, Sequence
from griffe import Attribute, Class, Function, Module
- from jinja2 import Environment
from jinja2.runtime import Context
from mkdocstrings import CollectorItem
@@ -160,8 +157,7 @@ def do_format_signature(
The same code, formatted.
"""
env = context.environment
- # YORE: Bump 2: Replace `do_get_template(env, "signature")` with `"signature.html.jinja"` within line.
- template = env.get_template(do_get_template(env, "signature"))
+ template = env.get_template("signature.html.jinja")
if annotations is None:
new_context = context.parent
@@ -222,8 +218,7 @@ def do_format_attribute(
The same code, formatted.
"""
env = context.environment
- # YORE: Bump 2: Replace `do_get_template(env, "expression")` with `"expression.html.jinja"` within line.
- template = env.get_template(do_get_template(env, "expression"))
+ template = env.get_template("expression.html.jinja")
annotations = context.parent["config"].show_signature_annotations
signature = str(attribute_path).strip()
@@ -276,7 +271,8 @@ def do_order_members(
if isinstance(members_list, list) and members_list:
sorted_members = []
members_dict = {member.name: member for member in members}
- for name in members_list:
+ for item in members_list:
+ name = item if isinstance(item, str) else item.name
if name in members_dict:
sorted_members.append(members_dict[name])
return sorted_members
@@ -288,76 +284,6 @@ def do_order_members(
return members
-# YORE: Bump 2: Remove block.
-@lru_cache
-def _warn_crossref() -> None:
- warnings.warn(
- "The `crossref` filter is deprecated and will be removed in a future version",
- DeprecationWarning,
- stacklevel=1,
- )
-
-
-# YORE: Bump 2: Remove block.
-def do_crossref(path: str, *, brief: bool = True) -> Markup:
- """Deprecated. Filter to create cross-references.
-
- Parameters:
- path: The path to link to.
- brief: Show only the last part of the path, add full path as hover.
-
- Returns:
- Markup text.
- """
- _warn_crossref()
- full_path = path
- if brief:
- path = full_path.split(".")[-1]
- return Markup("{text}
"
- return Markup(text).format(**variables) # noqa: S704
-
-
_split_path_re = re.compile(r"([.(]?)([\w]+)(\))?")
_splitable_re = re.compile(r"[().]")
@@ -445,6 +371,7 @@ def do_filter_objects(
members_list: bool | list[str] | None = None,
inherited_members: bool | list[str] = False,
keep_no_docstrings: bool = True,
+ apply_options: bool = False,
) -> list[Object | Alias]:
"""Filter a dictionary of objects based on their docstrings.
@@ -458,6 +385,7 @@ def do_filter_objects(
When given and not empty, ignore filters and docstrings presence/absence.
inherited_members: Whether to keep inherited members or exclude them.
keep_no_docstrings: Whether to keep objects with no/empty docstrings (recursive check).
+ apply_options: Whether to apply options to the objects.
Returns:
A list of objects.
@@ -486,9 +414,14 @@ def do_filter_objects(
if members_list is not None:
# Return selected members (keeping any pre-selected inherited members).
- return [
- obj for obj in objects if obj.name in set(members_list) or (inherited_members_specified and obj.inherited)
- ]
+ if apply_options:
+ for member in members_list:
+ if not isinstance(member, str):
+ name = member.name
+ if (obj := objects_dictionary[name]) and member.options:
+ obj.extra["mkdocstrings"]["options"] = member.options
+ names = {member if isinstance(member, str) else member.name for member in members_list}
+ return [obj for obj in objects if obj.name in names or (inherited_members_specified and obj.inherited)]
# Use filters and docstrings.
if filters == "public":
@@ -572,39 +505,19 @@ def formatter(code: str, line_length: int) -> str:
return formatter
-# YORE: Bump 2: Remove line.
-@pass_environment
-# YORE: Bump 2: Replace `env: Environment, ` with `` within line.
-# YORE: Bump 2: Replace `str | ` with `` within line.
-def do_get_template(env: Environment, obj: str | Object) -> str:
+def do_get_template(obj: Object) -> str:
"""Get the template name used to render an object.
Parameters:
- env: The Jinja environment, passed automatically.
obj: A Griffe object, or a template name.
Returns:
A template name.
"""
- name = obj
- if isinstance(obj, (Alias, Object)):
- extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
- if name := extra_data.get("template", ""):
- return name
- name = obj.kind.value
- # YORE: Bump 2: Replace block with `return f"{name}.html.jinja"`.
- try:
- template = env.get_template(f"{name}.html")
- except TemplateNotFound:
- return f"{name}.html.jinja"
- our_template = Path(template.filename).is_relative_to(Path(__file__).parent.parent) # type: ignore[arg-type]
- if our_template:
- return f"{name}.html.jinja"
- _logger.warning(
- f"DeprecationWarning: Overriding '{name}.html' is deprecated, override '{name}.html.jinja' instead. ",
- once=True,
- )
- return f"{name}.html"
+ extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
+ if template := extra_data.get("template", ""):
+ return template
+ return f"{obj.kind.value}.html.jinja"
@pass_context
diff --git a/src/mkdocstrings_handlers/python/config.py b/src/mkdocstrings_handlers/python/config.py
deleted file mode 100644
index 5edab089..00000000
--- a/src/mkdocstrings_handlers/python/config.py
+++ /dev/null
@@ -1,17 +0,0 @@
-"""Deprecated. Import from `mkdocstrings_handlers.python` directly."""
-
-# YORE: Bump 2: Remove file.
-
-import warnings
-from typing import Any
-
-from mkdocstrings_handlers.python._internal import config
-
-
-def __getattr__(name: str) -> Any:
- warnings.warn(
- "Importing from `mkdocstrings_handlers.python.config` is deprecated. Import from `mkdocstrings_handlers.python` directly.",
- DeprecationWarning,
- stacklevel=2,
- )
- return getattr(config, name)
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
deleted file mode 100644
index 5b334860..00000000
--- a/src/mkdocstrings_handlers/python/handler.py
+++ /dev/null
@@ -1,17 +0,0 @@
-"""Deprecated. Import from `mkdocstrings_handlers.python` directly."""
-
-# YORE: Bump 2: Remove file.
-
-import warnings
-from typing import Any
-
-from mkdocstrings_handlers.python._internal import handler
-
-
-def __getattr__(name: str) -> Any:
- warnings.warn(
- "Importing from `mkdocstrings_handlers.python.handler` is deprecated. Import from `mkdocstrings_handlers.python` directly.",
- DeprecationWarning,
- stacklevel=2,
- )
- return getattr(handler, name)
diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py
deleted file mode 100644
index 5cd4d200..00000000
--- a/src/mkdocstrings_handlers/python/rendering.py
+++ /dev/null
@@ -1,17 +0,0 @@
-"""Deprecated. Import from `mkdocstrings_handlers.python` directly."""
-
-# YORE: Bump 2: Remove file.
-
-import warnings
-from typing import Any
-
-from mkdocstrings_handlers.python._internal import rendering
-
-
-def __getattr__(name: str) -> Any:
- warnings.warn(
- "Importing from `mkdocstrings_handlers.python.rendering` is deprecated. Import from `mkdocstrings_handlers.python` directly.",
- DeprecationWarning,
- stacklevel=2,
- )
- return getattr(rendering, name)
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
deleted file mode 100644
index 37c8702c..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/attribute.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/attribute.html' is deprecated, extend '_base/attribute.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 519590e5..e13cae12 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
@@ -39,7 +39,7 @@ Context:
role="data" if attribute.parent.kind.value == "module" else "attr",
id=html_id,
class="doc doc-heading",
- toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute.name),
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label or attribute.name),
) %}
{% block heading scoped %}
@@ -48,7 +48,7 @@ Context:
This block renders the heading for the attribute.
-#}
{% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.heading and root %}
+ {% if config.heading %}
{{ config.heading }}
{% elif config.separate_signature %}
{{ attribute_name }}
@@ -66,8 +66,7 @@ Context:
This block renders the labels for the attribute.
-#}
{% with labels = attribute.labels %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "labels"|get_template with context %}
+ {% include "labels.html.jinja" with context %}
{% endwith %}
{% endblock labels %}
@@ -91,7 +90,7 @@ Context:
{% filter heading(heading_level,
role="data" if attribute.parent.kind.value == "module" else "attr",
id=html_id,
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name),
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label or attribute_name),
hidden=True,
) %}
{% endfilter %}
@@ -113,8 +112,7 @@ Context:
This block renders the docstring for the attribute.
-#}
{% with docstring_sections = attribute.docstring.parsed %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "docstring"|get_template with context %}
+ {% include "docstring.html.jinja" with context %}
{% endwith %}
{% endblock docstring %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html b/src/mkdocstrings_handlers/python/templates/material/_base/children.html
deleted file mode 100644
index eada68e8..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/children.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/children.html' is deprecated, extend '_base/children.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 0b9fcd64..7d2a2ffb 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja
@@ -21,36 +21,26 @@ Context:
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name),
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label or class.name),
) %}
{% block heading scoped %}
@@ -47,15 +47,14 @@ Context:
This block renders the heading for the class.
-#}
{% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.heading and root %}
+ {% if config.heading %}
{{ config.heading }}
{% elif config.separate_signature %}
{{ class_name }}
{% elif config.merge_init_into_class and "__init__" in all_members %}
{% with function = all_members["__init__"] %}
{%+ filter highlight(language="python", inline=True) -%}
- {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}
- {{ class_name }}{% include "signature"|get_template with context %}
+ {{ class_name }}{% include "signature.html.jinja" with context %}
{%- endfilter %}
{% endwith %}
{% else %}
@@ -69,8 +68,7 @@ Context:
This block renders the labels for the class.
-#}
{% with labels = class.labels %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "labels"|get_template with context %}
+ {% include "labels.html.jinja" with context %}
{% endwith %}
{% endblock labels %}
@@ -110,7 +108,7 @@ Context:
{% filter heading(heading_level,
role="class",
id=html_id,
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name),
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label or class.name),
hidden=True,
) %}
{% endfilter %}
@@ -136,8 +134,7 @@ Context:
Bases: {% for expression in class.bases -%}
{%- with backlink_type = "subclassed-by" -%}
- {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}
- {%- include "expression"|get_template with context -%}
+ {%- include "expression.html.jinja" with context -%}
{%- endwith -%}
{% if not loop.last %}, {% endif %}
{% endfor -%}
@@ -151,8 +148,7 @@ Context:
This block renders the docstring for the class.
-#}
{% with docstring_sections = class.docstring.parsed %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "docstring"|get_template with context %}
+ {% include "docstring.html.jinja" with context %}
{% endwith %}
{% if config.merge_init_into_class %}
{# We don't want to merge the inherited `__init__` method docstring into the class docstring #}
@@ -161,8 +157,7 @@ Context:
{% if "__init__" in check_members and check_members["__init__"].has_docstring %}
{% with function = check_members["__init__"] %}
{% with obj = function, docstring_sections = function.docstring.parsed %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "docstring"|get_template with context %}
+ {% include "docstring.html.jinja" with context %}
{% endwith %}
{% endwith %}
{% endif %}
@@ -179,8 +174,7 @@ Context:
This block renders auto-summaries for classes, methods, and attributes.
-#}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "summary"|get_template with context %}
+ {% include "summary.html.jinja" with context %}
{% endblock summary %}
{% block source scoped %}
@@ -226,8 +220,7 @@ Context:
-#}
{% set root = False %}
{% set heading_level = heading_level + 1 %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "children"|get_template with context %}
+ {% include "children.html.jinja" with context %}
{% endblock children %}
{% endblock contents %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{{ attribute.name }}
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- ({% include "expression"|get_template with context %}
)
+ ({% include "expression.html.jinja" with context %}
)
{% endwith %}
{% endif %}
–
@@ -98,8 +95,7 @@ Context:
TYPE:
{% with expression = attribute.annotation %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html
deleted file mode 100644
index 9c04b145..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/docstring/classes.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/docstring/classes.html' is deprecated, extend '_base/docstring/classes.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 09a5b758..b139a761 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
@@ -15,8 +15,7 @@ Context:
{{ log.debug("Rendering classes section") }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
{% if config.docstring_section_style == "table" %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html
deleted file mode 100644
index 4f66600f..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/docstring/examples.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/docstring/examples.html' is deprecated, extend '_base/docstring/examples.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 09293cfb..32360f7d 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
@@ -15,8 +15,7 @@ Context:
{{ log.debug("Rendering examples section") }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
{{ section.title or lang.t("Examples:") }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html deleted file mode 100644 index 906658b4..00000000 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html +++ /dev/null @@ -1,10 +0,0 @@ -{# YORE: Bump 2: Remove file. #} -{% extends "_base/docstring/functions.html.jinja" %} - -{% block logs scoped %} - {{ super() }} - {{ log.warning( - "DeprecationWarning: Extending '_base/docstring/functions.html' is deprecated, extend '_base/docstring/functions.html.jinja' instead. ", - once=True, - ) }} -{% endblock logs %} 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 dd33984f..afec8f60 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 @@ -15,8 +15,7 @@ Context: {{ log.debug("Rendering functions section") }} {% endblock logs %} -{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #} -{% import "language"|get_template as lang with context %} +{% import "language.html.jinja" as lang with context %} {#- Language module providing the `t` translation method. -#} {% if config.docstring_section_style == "table" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html deleted file mode 100644 index 7b0dcc51..00000000 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html +++ /dev/null @@ -1,10 +0,0 @@ -{# YORE: Bump 2: Remove file. #} -{% extends "_base/docstring/modules.html.jinja" %} - -{% block logs scoped %} - {{ super() }} - {{ log.warning( - "DeprecationWarning: Extending '_base/docstring/modules.html' is deprecated, extend '_base/docstring/modules.html.jinja' instead. ", - once=True, - ) }} -{% endblock logs %} 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 106e6bf6..5556cf15 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 @@ -15,8 +15,7 @@ Context: {{ log.debug("Rendering modules section") }} {% endblock logs %} -{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #} -{% import "language"|get_template as lang with context %} +{% import "language.html.jinja" as lang with context %} {#- Language module providing the `t` translation method. -#} {% if config.docstring_section_style == "table" %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html deleted file mode 100644 index 02261331..00000000 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html +++ /dev/null @@ -1,10 +0,0 @@ -{# YORE: Bump 2: Remove file. #} -{% extends "_base/docstring/other_parameters.html.jinja" %} - -{% block logs scoped %} - {{ super() }} - {{ log.warning( - "DeprecationWarning: Extending '_base/docstring/other_parameters.html' is deprecated, extend '_base/docstring/other_parameters.html.jinja' instead. ", - once=True, - ) }} -{% endblock logs %} 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 66940069..5e0a75f5 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 @@ -15,8 +15,7 @@ Context: {{ log.debug("Rendering other parameters section") }} {% endblock logs %} -{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #} -{% import "language"|get_template as lang with context %} +{% import "language.html.jinja" as lang with context %} {#- Language module providing the `t` translation method. -#} {% if config.docstring_section_style == "table" %} @@ -38,8 +37,7 @@ Context:{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{{ parameter.name }}
{% if parameter.annotation %}
{% with expression = parameter.annotation, backlink_type = "used-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- ({% include "expression"|get_template with context %}
)
+ ({% include "expression.html.jinja" with context %}
)
{% endwith %}
{% endif %}
–
@@ -98,8 +95,7 @@ Context:
{{ lang.t("TYPE:") }}
{% with expression = parameter.annotation, backlink_type = "used-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html
deleted file mode 100644
index f5292150..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/docstring/parameters.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/docstring/parameters.html' is deprecated, extend '_base/docstring/parameters.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 1035ddf7..793a2b23 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
@@ -15,8 +15,7 @@ Context:
{{ log.debug("Rendering parameters section") }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
{% if config.docstring_section_style == "table" %}
@@ -53,8 +52,7 @@ Context:
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% else %}
{{ lang.t("required") }}
@@ -100,12 +97,10 @@ Context:
{% endif %}
{% if parameter.annotation %}
{% with expression = parameter.annotation, backlink_type = "used-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- ({% include "expression"|get_template with context %}
+ ({% include "expression.html.jinja" with context %}
{%- if parameter.default %}, {{ lang.t("default:") }}
{% with expression = parameter.default, backlink_type = "used-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %})
{% endwith %}
@@ -155,8 +150,7 @@ Context:
{{ lang.t("TYPE:") }}
{% with expression = parameter.annotation, backlink_type = "used-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
@@ -164,8 +158,7 @@ Context:
{{ lang.t("DEFAULT:") }}
{% with expression = parameter.default, backlink_type = "used-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html
deleted file mode 100644
index 38a21e89..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/docstring/raises.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/docstring/raises.html' is deprecated, extend '_base/docstring/raises.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 cd034c0e..7d548035 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
@@ -15,8 +15,7 @@ Context:
{{ log.debug("Rendering raises section") }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
{% if config.docstring_section_style == "table" %}
@@ -36,8 +35,7 @@ Context:
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
–
{% endif %}
@@ -88,8 +85,7 @@ Context:
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% if receives.name %}){% endif %}
{% endwith %}
{% endif %}
@@ -97,8 +94,7 @@ Context:
{% elif receives.annotation %}
{% with expression = receives.annotation, backlink_type = "received-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
@@ -112,8 +108,7 @@ Context:
{{ lang.t("TYPE:") }}
{% with expression = receives.annotation, backlink_type = "received-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html
deleted file mode 100644
index b608af5f..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/docstring/returns.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/docstring/returns.html' is deprecated, extend '_base/docstring/returns.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 bc8ee4ff..da693da7 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
@@ -15,8 +15,7 @@ Context:
{{ log.debug("Rendering returns section") }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
{% if config.docstring_section_style == "table" %}
@@ -39,8 +38,7 @@ Context:
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% if returns.name %}){% endif %}
{% endwith %}
{% endif %}
@@ -97,8 +94,7 @@ Context:
{% elif returns.annotation %}
{% with expression = returns.annotation, backlink_type = "returned-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
@@ -112,8 +108,7 @@ Context:
{{ lang.t("TYPE:") }}
{% with expression = returns.annotation, backlink_type = "returned-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html
deleted file mode 100644
index 9eba72ab..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/docstring/warns.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/docstring/warns.html' is deprecated, extend '_base/docstring/warns.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 d5a24262..6f7e69de 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
@@ -15,8 +15,7 @@ Context:
{{ log.debug("Rendering warns section") }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
{% if config.docstring_section_style == "table" %}
@@ -36,8 +35,7 @@ Context:
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
–
{% endif %}
@@ -88,8 +85,7 @@ Context:
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
{% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% if yields.name %}){% endif %}
{% endwith %}
{% endif %}
@@ -97,8 +94,7 @@ Context:
{% elif yields.annotation %}
{% with expression = yields.annotation, backlink_type = "yielded-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
{% endif %}
@@ -112,8 +108,7 @@ Context:
{{ lang.t("TYPE:") }}:
{% with expression = yields.annotation, backlink_type = "yielded-by" %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "expression"|get_template with context %}
+ {% include "expression.html.jinja" with context %}
{% endwith %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html
deleted file mode 100644
index 8c84928c..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/expression.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/expression.html' is deprecated, extend '_base/expression.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html
deleted file mode 100644
index 4afd930b..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/function.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/function.html' is deprecated, extend '_base/function.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 21888939..403acbf3 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
@@ -17,8 +17,7 @@ Context:
{{ log.debug("Rendering " + function.path) }}
{% endblock logs %}
-{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
-{% import "language"|get_template as lang with context %}
+{% import "language.html.jinja" as lang with context %}
{#- Language module providing the `t` translation method. -#}
')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name),
+ toc_label=(('
')|safe if config.show_symbol_type_toc else '') + (config.toc_label or function.name),
) %}
{% block heading scoped %}
@@ -54,14 +53,13 @@ Context:
This block renders the heading for the function.
-#}
{% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.heading and root %}
+ {% if config.heading %}
{{ config.heading }}
{% elif config.separate_signature %}
{{ function_name }}
{% else %}
{%+ filter highlight(language="python", inline=True) -%}
- {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}
- {{ function_name }}{% include "signature"|get_template with context %}
+ {{ function_name }}{% include "signature.html.jinja" with context %}
{%- endfilter %}
{% endif %}
{% endblock heading %}
@@ -72,8 +70,7 @@ Context:
This block renders the labels for the function.
-#}
{% with labels = function.labels %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "labels"|get_template with context %}
+ {% include "labels.html.jinja" with context %}
{% endwith %}
{% endblock labels %}
@@ -108,7 +105,7 @@ Context:
heading_level,
role="function",
id=html_id,
- toc_label=(('
')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name),
+ toc_label=(('
')|safe if config.show_symbol_type_toc else '') + (config.toc_label or function.name),
hidden=True,
) %}
{% endfilter %}
@@ -130,8 +127,7 @@ Context:
This block renders the docstring for the function.
-#}
{% with docstring_sections = function.docstring.parsed %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "docstring"|get_template with context %}
+ {% include "docstring.html.jinja" with context %}
{% endwith %}
{% endblock docstring %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html b/src/mkdocstrings_handlers/python/templates/material/_base/labels.html
deleted file mode 100644
index cda79114..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/labels.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/labels.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/labels.html' is deprecated, extend '_base/labels.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html b/src/mkdocstrings_handlers/python/templates/material/_base/language.html
deleted file mode 100644
index a5a86545..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/language.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/language.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/language.html' is deprecated, extend '_base/language.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
index 5a4b773e..31ecfdd6 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/language.html.jinja
@@ -7,15 +7,12 @@
-#}
{% endblock logs %}
-{# YORE: Bump 2: Replace `| get_template` with `~ ".html.jinja"` within line. #}
-{% set lang_pth = "languages/" ~ locale | get_template %}
+{% set lang_pth = "languages/" ~ locale ~ ".html.jinja" %}
{% if lang_pth is existing_template %}
{% import lang_pth as lang %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% import "languages/en"|get_template as fallback %}
+ {% import "languages/en.html.jinja" as fallback %}
{% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %}
{% else %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% import "languages/en"|get_template as lang %}
+ {% import "languages/en.html.jinja" as lang %}
{% macro t(key) %}{{ lang.t(key) }}{% endmacro %}
{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
deleted file mode 100644
index 2f050a32..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/languages/en.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/languages/en.html' is deprecated, extend '_base/languages/en.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
deleted file mode 100644
index 1f3095f4..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/languages/ja.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/languages/ja.html' is deprecated, extend '_base/languages/ja.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
deleted file mode 100644
index b58b0479..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/languages/zh.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/languages/zh.html' is deprecated, extend '_base/languages/zh.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html b/src/mkdocstrings_handlers/python/templates/material/_base/module.html
deleted file mode 100644
index dcda15ea..00000000
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{# YORE: Bump 2: Remove file. #}
-{% extends "_base/module.html.jinja" %}
-
-{% block logs scoped %}
- {{ super() }}
- {{ log.warning(
- "DeprecationWarning: Extending '_base/module.html' is deprecated, extend '_base/module.html.jinja' instead. ",
- once=True,
- ) }}
-{% endblock logs %}
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 283f2654..cc9f26f3 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
@@ -38,7 +38,7 @@ Context:
role="module",
id=html_id,
class="doc doc-heading",
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name),
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label or module.name),
) %}
{% block heading scoped %}
@@ -47,7 +47,7 @@ Context:
This block renders the heading for the module.
-#}
{% if config.show_symbol_type_heading %}
{% endif %}
- {% if config.heading and root %}
+ {% if config.heading %}
{{ config.heading }}
{% elif config.separate_signature %}
{{ module_name }}
@@ -62,8 +62,7 @@ Context:
This block renders the labels for the module.
-#}
{% with labels = module.labels %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "labels"|get_template with context %}
+ {% include "labels.html.jinja" with context %}
{% endwith %}
{% endblock labels %}
@@ -74,7 +73,7 @@ Context:
{% filter heading(heading_level,
role="module",
id=html_id,
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name),
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label or module.name),
hidden=True,
) %}
{% endfilter %}
@@ -96,8 +95,7 @@ Context:
This block renders the docstring for the module.
-#}
{% with docstring_sections = module.docstring.parsed %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "docstring"|get_template with context %}
+ {% include "docstring.html.jinja" with context %}
{% endwith %}
{% endblock docstring %}
@@ -110,8 +108,7 @@ Context:
This block renders auto-summaries for classes, methods, and attributes.
-#}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "summary"|get_template with context %}
+ {% include "summary.html.jinja" with context %}
{% endblock summary %}
{% block children scoped %}
@@ -121,8 +118,7 @@ Context:
-#}
{% set root = False %}
{% set heading_level = heading_level + 1 %}
- {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
- {% include "children"|get_template with context %}
+ {% include "children.html.jinja" with context %}
{% endblock children %}
{% endblock contents %}