chore: Mark legacy code with YORE comments

Author: pawamoy

src/mkdocstrings_handlers/python/_internal/config.py

@@ -37,6 +37,7 @@
     if getattr(pydantic, "__version__", "1.").startswith("1."):
         raise ImportError  # noqa: TRY301
 
+    # YORE: EOL 3.9: Remove block.
     if sys.version_info < (3, 10):
         try:
             import eval_type_backport  # noqa: F401

src/mkdocstrings_handlers/python/_internal/handler.py

@@ -33,10 +33,10 @@
     from mkdocs.config.defaults import MkDocsConfig
 
 
+# YORE: EOL 3.10: Replace block with line 2.
 if sys.version_info >= (3, 11):
     from contextlib import chdir
 else:
-    # TODO: remove once support for Python 3.10 is dropped
     from contextlib import contextmanager
 
     @contextmanager
@@ -54,6 +54,7 @@ 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. "
@@ -94,14 +95,18 @@ 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: Replace block with `self.global_options = config.options`.
+        # 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`)."""
 
+        # YORE: Bump 2: Replace `# ` with `` within block.
+        # self.global_options = config.options
+        # """The global configuration options (in `mkdocs.yml`)."""
+
         # Warn if user overrides base templates.
         if self.custom_templates:
             for theme_dir in base_dir.joinpath(self.custom_templates, "python").iterdir():

src/mkdocstrings_handlers/python/_internal/rendering.py

@@ -148,7 +148,7 @@ def do_format_signature(
         The same code, formatted.
     """
     env = context.environment
-    # TODO: Stop using `do_get_template` when `*.html` templates are removed.
+    # YORE: Bump 2: Replace `do_get_template(env, "signature")` with `"signature.html.jinja"`.
     template = env.get_template(do_get_template(env, "signature"))
 
     if annotations is None:
@@ -208,7 +208,7 @@ def do_format_attribute(
         The same code, formatted.
     """
     env = context.environment
-    # TODO: Stop using `do_get_template` when `*.html` templates are removed.
+    # YORE: Bump 2: Replace `do_get_template(env, "expression")` with `"expression.html.jinja"`.
     template = env.get_template(do_get_template(env, "expression"))
     annotations = context.parent["config"].show_signature_annotations
 
@@ -269,6 +269,7 @@ def do_order_members(
     return sorted(members, key=_order_map[order])
 
 
+# YORE: Bump 2: Remove block.
 @lru_cache
 def _warn_crossref() -> None:
     warnings.warn(
@@ -278,6 +279,7 @@ def _warn_crossref() -> None:
     )
 
 
+# YORE: Bump 2: Remove block.
 def do_crossref(path: str, *, brief: bool = True) -> Markup:
     """Deprecated. Filter to create cross-references.
 
@@ -298,6 +300,7 @@ def do_crossref(path: str, *, brief: bool = True) -> Markup:
     )
 
 
+# YORE: Bump 2: Remove block.
 @lru_cache
 def _warn_multi_crossref() -> None:
     warnings.warn(
@@ -307,6 +310,7 @@ def _warn_multi_crossref() -> None:
     )
 
 
+# YORE: Bump 2: Remove block.
 def do_multi_crossref(text: str, *, code: bool = True) -> Markup:
     """Deprecated. Filter to create cross-references.
 
@@ -520,7 +524,10 @@ 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 | Template:
     """Get the template name used to render an object.
 
@@ -537,6 +544,7 @@ def do_get_template(env: Environment, obj: str | Object) -> str | Template:
         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:

src/mkdocstrings_handlers/python/config.py

@@ -1,6 +1,6 @@
 """Deprecated. Import from `mkdocstrings_handlers.python` directly."""
 
-# YORE: Bump 1: Remove file.
+# YORE: Bump 2: Remove file.
 
 import warnings
 from typing import Any

src/mkdocstrings_handlers/python/handler.py

@@ -1,6 +1,6 @@
 """Deprecated. Import from `mkdocstrings_handlers.python` directly."""
 
-# YORE: Bump 1: Remove file.
+# YORE: Bump 2: Remove file.
 
 import warnings
 from typing import Any

src/mkdocstrings_handlers/python/rendering.py

@@ -1,6 +1,6 @@
 """Deprecated. Import from `mkdocstrings_handlers.python` directly."""
 
-# YORE: Bump 1: Remove file.
+# YORE: Bump 2: Remove file.
 
 import warnings
 from typing import Any

src/mkdocstrings_handlers/python/templates/material/_base/attribute.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/attribute.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -64,6 +64,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 %}
           {% endwith %}
         {% endblock labels %}
@@ -110,6 +111,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 %}
           {% endwith %}
         {% endblock docstring %}

src/mkdocstrings_handlers/python/templates/material/_base/children.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/children.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/class.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/class.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

@@ -51,9 +51,10 @@ Context:
             <span class="doc doc-object-name doc-class-name">{{ config.heading if config.heading and root else class_name }}</span>
           {% elif config.merge_init_into_class and "__init__" in all_members %}
             {% with function = all_members["__init__"] %}
-              {%+ filter highlight(language="python", inline=True) %}
+              {%+ 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 %}
-              {% endfilter %}
+              {%- endfilter %}
             {% endwith %}
           {% else %}
             <code>{{ class_name }}</code>
@@ -66,6 +67,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 %}
           {% endwith %}
         {% endblock labels %}
@@ -132,6 +134,7 @@ Context:
               Bases: {% for expression in class.bases -%}
                 <code>
                   {%- with backlink_type = "subclassed-by" -%}
+                    {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}
                     {%- include "expression"|get_template with context -%}
                   {%- endwith -%}
                 </code>{% if not loop.last %}, {% endif %}
@@ -146,6 +149,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 %}
           {% endwith %}
           {% if config.merge_init_into_class %}
@@ -155,6 +159,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 %}
                   {% endwith %}
                 {% endwith %}
@@ -172,6 +177,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 %}
         {% endblock summary %}
 
@@ -218,6 +224,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 %}
         {% endblock children %}
       {% endblock contents %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring.html.jinja

@@ -24,30 +24,43 @@ Context:
       {% if config.show_docstring_description and section.kind.value == "text" %}
         {{ section.value|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
       {% elif config.show_docstring_attributes and section.kind.value == "attributes" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/attributes"|get_template with context %}
       {% elif config.show_docstring_functions and section.kind.value == "functions" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/functions"|get_template with context %}
       {% elif config.show_docstring_classes and section.kind.value == "classes" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/classes"|get_template with context %}
       {% elif config.show_docstring_modules and section.kind.value == "modules" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/modules"|get_template with context %}
       {% elif config.show_docstring_parameters and section.kind.value == "parameters" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/parameters"|get_template with context %}
       {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/other_parameters"|get_template with context %}
       {% elif config.show_docstring_raises and section.kind.value == "raises" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/raises"|get_template with context %}
       {% elif config.show_docstring_warns and section.kind.value == "warns" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/warns"|get_template with context %}
       {% elif config.show_docstring_yields and section.kind.value == "yields" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/yields"|get_template with context %}
       {% elif config.show_docstring_receives and section.kind.value == "receives" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/receives"|get_template with context %}
       {% elif config.show_docstring_returns and section.kind.value == "returns" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/returns"|get_template with context %}
       {% elif config.show_docstring_examples and section.kind.value == "examples" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/examples"|get_template with context %}
       {% elif config.show_docstring_description and section.kind.value == "admonition" %}
+        {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
         {% include "docstring/admonition"|get_template with context %}
       {% endif %}
     {% endfor %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/admonition.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/attributes.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja

@@ -15,6 +15,7 @@ Context:
   {{ log.debug("Rendering attributes section") }}
 {% endblock logs %}
 
+{# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
 {% import "language"|get_template as lang with context %}
 {#- Language module providing the `t` translation method. -#}
 
@@ -37,6 +38,7 @@ Context:
             <td>
               {% if attribute.annotation %}
                 {% with expression = attribute.annotation %}
+                  {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -61,6 +63,7 @@ Context:
           <b><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></b>
           {% if attribute.annotation %}
             {% with expression = attribute.annotation %}
+              {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
               (<code>{% include "expression"|get_template with context %}</code>)
             {% endwith %}
           {% endif %}
@@ -95,6 +98,7 @@ Context:
                   <span class="doc-attribute-annotation">
                     <b>TYPE:</b>
                     {% with expression = attribute.annotation %}
+                      {# YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. #}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/classes.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja

@@ -15,6 +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 %}
 {#- Language module providing the `t` translation method. -#}
 

src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/examples.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html.jinja

@@ -15,6 +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 %}
 {#- Language module providing the `t` translation method. -#}
 

src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/functions.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja

@@ -15,6 +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 %}
 {#- Language module providing the `t` translation method. -#}
 

src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/modules.html.jinja" %}
 
 {% block logs scoped %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja

@@ -15,6 +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 %}
 {#- Language module providing the `t` translation method. -#}
 

src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html

@@ -1,3 +1,4 @@
+{# YORE: Bump 2: Remove file. #}
 {% extends "_base/docstring/other_parameters.html.jinja" %}
 
 {% block logs scoped %}