refactor: Remove deprecated parts

- Base collector class
- Base renderer class
- Watch feature
- Selection and rendering keys support (YAML options)
- `mkdocstrings.handlers` namespace
  (when importing handlers and finding templates)

config/mypy.ini

@@ -3,5 +3,3 @@ ignore_missing_imports = true
 exclude = tests/fixtures/
 warn_unused_ignores = true
 show_error_codes = true
-namespace_packages = true
-explicit_package_bases = true

config/ruff.toml

@@ -65,7 +65,6 @@ ignore = [
     "E501",  # Line too long
     "ERA001",  # Commented out code
     "G004",  # Logging statement uses f-string
-    "INP001",  # File is part of an implicit namespace package
     "PLR0911",  # Too many return statements
     "PLR0912",  # Too many branches
     "PLR0913",  # Too many arguments to function call

docs/usage/handlers.md

@@ -14,11 +14,8 @@ Since version 0.18, a new, experimental Python handler is available.
 It is based on [Griffe](https://github.com/mkdocstrings/griffe),
 which is an improved version of [pytkdocs](https://github.com/mkdocstrings/pytkdocs).
 
-Note that the experimental handler does not yet support third-party libraries
-like Django, Marshmallow, Pydantic, etc.
-It is also not completely ready to handle dynamically built objects,
-like classes built with a call to `type(...)`.
-For most other cases, the experimental handler will work just fine.
+Note that the experimental handler does not yet support all third-party libraries
+that the legacy handler supported.
 
 If you want to keep using the legacy handler as long as possible,
 you can depend on `mkdocstrings-python-legacy` directly,
@@ -51,18 +48,13 @@ dependencies = [
 ]
 ```
 
-#### Handler options
-
-- `setup_commands` is not yet implemented. In most cases, you won't need it,
-  since by default the new handler does not execute the code.
-
 #### Selection options
 
 WARNING: Since *mkdocstrings* 0.19, the YAML `selection` key is merged into the `options` key.
 
 - [x] `filters` is implemented, and used as before.
 - [x] `members` is implemented, and used as before.
-- [ ] `inherited_members` is not yet implemented.
+- [x] `inherited_members` is implemented.
 - [x] `docstring_style` is implemented, and used as before,
   except for the `restructured-text` style which is renamed `sphinx`.
   Numpy-style is now built-in, so you can stop depending on `pytkdocs[numpy-style]`
@@ -83,13 +75,13 @@ WARNING: Since *mkdocstrings* 0.19, the YAML `rendering` key is merged into the
 Every previous option is supported.
 Additional options are available:
 
-- `separate_signature`: Render the signature (or attribute value) in a code block below the heading,
+- [x] `separate_signature`: Render the signature (or attribute value) in a code block below the heading,
   instead as inline code. Useful for long signatures. If Black is installed,
   the signature is formatted. Default: `False`.
-- `line_length`: The maximum line length to use when formatting signatures. Default: `60`.
-- `show_submodules`: Whether to render submodules of a module when iterating on children.
+- [x] `line_length`: The maximum line length to use when formatting signatures. Default: `60`.
+- [x] `show_submodules`: Whether to render submodules of a module when iterating on children.
   Default: `False`.
-- `docstring_section_style`: The style to use to render docstring sections such as attributes,
+- [x] `docstring_section_style`: The style to use to render docstring sections such as attributes,
   parameters, etc. Available styles: `table` (default), `list` and `spacy`. The SpaCy style
   is a poor implementation of their [table style](https://spacy.io/api/doc/#init).
   We are open to improvements through PRs!
@@ -99,34 +91,8 @@ See [all the handler's options](https://mkdocstrings.github.io/python/usage/).
 #### Templates
 
 Templates are mostly the same as before, but the file layout has changed,
-as well as some file names. Here is the new tree:
-
-```
-📁 theme/
-├── 📄 attribute.html
-├── 📄 children.html
-├── 📄 class.html
-├── 📁 docstring/
-│   ├── 📄 admonition.html
-│   ├── 📄 attributes.html
-│   ├── 📄 examples.html
-│   ├── 📄 other_parameters.html
-│   ├── 📄 parameters.html
-│   ├── 📄 raises.html
-│   ├── 📄 receives.html
-│   ├── 📄 returns.html
-│   ├── 📄 warns.html
-│   └── 📄 yields.html
-├── 📄 docstring.html
-├── 📄 expression.html
-├── 📄 function.html
-├── 📄 labels.html
-├── 📄 module.html
-└── 📄 signature.html
-```
-
-See them [in the handler repository](https://github.com/mkdocstrings/python/tree/8fc8ea5b112627958968823ef500cfa46b63613e/src/mkdocstrings_handlers/python/templates/material). See the documentation about the Python handler templates:
-https://mkdocstrings.github.io/python/customization/#templates.
+as well as some file names.
+See [the documentation about the Python handler templates](https://mkdocstrings.github.io/python/usage/customization/#templates).
 
 ## Custom handlers
 
@@ -213,7 +179,7 @@ If your theme's HTML requires CSS to go along with it, put it into a file named
 `mkdocstrings_handlers/custom_handler/templates/some_theme/style.css`, then this will be
 included into the final site automatically if this handler is ever used.
 Alternatively, you can put the CSS as a string into the `extra_css` variable of
-your renderer.
+your handler.
 
 Finally, it's possible to entirely omit templates, and tell *mkdocstrings*
 to use the templates of another handler. In you handler, override the
@@ -225,7 +191,7 @@ from mkdocstrings.handlers.base import BaseHandler
 
 
 class CobraHandler(BaseHandler):
-    def get_templates_dir(self, handler: str) -> Path:
+    def get_templates_dir(self, handler: str | None = None) -> Path:
         # use the python handler templates
         # (it assumes the python handler is installed)
         return super().get_templates_dir("python")

docs/usage/index.md

@@ -116,9 +116,6 @@ The above is equivalent to:
 - `enabled` **(New in version 0.20)**: Whether to enable the plugin. Defaults to `true`.
   Can be used to reduce build times when doing local development.
   Especially useful when used with environment variables (see example below).
-- `watch` **(deprecated)**: A list of directories to watch while serving the documentation.
-  See [Watch directories](#watch-directories). Deprecated in favor of the now built-in
-  [`watch` feature of MkDocs](https://www.mkdocs.org/user-guide/configuration/#watch).
 
 !!! example
     ```yaml title="mkdocs.yml"
@@ -334,30 +331,3 @@ plugins:
 - mkdocstrings:
     enable_inventory: false
 ```
-
-## Watch directories
-
-DANGER: **Deprecated since version 0.19.**  
-Instead, use the built-in [`watch` feature of MkDocs](https://www.mkdocs.org/user-guide/configuration/#watch).
-
-You can add directories to watch with the `watch` key.
-It accepts a list of paths.
-
-```yaml title="mkdocs.yml"
-plugins:
-  - mkdocstrings:
-      watch:
-        - src/my_package_1
-        - src/my_package_2
-```
-
-When serving your documentation
-and a change occur in one of the listed path,
-MkDocs will rebuild the site and reload the current page.
-
-NOTE: **The `watch` feature doesn't have special effects.**  
-Adding directories to the `watch` list doesn't have any other effect than watching for changes.
-For example, it will not tell the Python handler to look for packages in these paths
-(the paths are not added to the `PYTHONPATH` variable).
-If you want to tell Python where to look for packages and modules,
-see [Python Handler: Finding modules](https://mkdocstrings.github.io/python/usage/#finding-modules).

pyproject.toml

@@ -65,7 +65,6 @@ plugins = [
 
 [tool.pdm.build]
 package-dir = "src"
-includes = ["src/mkdocstrings"]
 editable-backend = "editables"
 
 [tool.pdm.dev-dependencies]

src/mkdocstrings/__init__.py

@@ -0,0 +1,4 @@
+"""mkdocstrings package.
+
+Automatic documentation from sources, for MkDocs.
+"""

src/mkdocstrings/extension.py

@@ -12,19 +12,17 @@
 ```yaml
 ::: some.identifier
     handler: python
-    selection:
+    options:
       option1: value1
       option2:
-        - value2a
-        - value2b
-    rendering:
+      - value2a
+      - value2b
       option_x: etc
 ```
 """
 
 from __future__ import annotations
 
-import functools
 import re
 from collections import ChainMap
 from typing import TYPE_CHECKING, Any, MutableSequence
@@ -184,13 +182,7 @@ def _process_block(
 
         global_options = handler_config.get("options", {})
         local_options = config.get("options", {})
-        deprecated_global_options = ChainMap(handler_config.get("selection", {}), handler_config.get("rendering", {}))
-        deprecated_local_options = ChainMap(config.get("selection", {}), config.get("rendering", {}))
-
-        options = ChainMap(local_options, deprecated_local_options, global_options, deprecated_global_options)
-
-        if deprecated_global_options or deprecated_local_options:
-            self._warn_about_options_key()
+        options = ChainMap(local_options, global_options)
 
         if heading_level:
             options = ChainMap(options, {"heading_level": heading_level})  # like setdefault
@@ -200,12 +192,12 @@ def _process_block(
             data: CollectorItem = handler.collect(identifier, options)
         except CollectionError as exception:
             log.error(str(exception))  # noqa: TRY400
-            if PluginError is SystemExit:  # When MkDocs 1.2 is sufficiently common, this can be dropped.
+            if PluginError is SystemExit:  # TODO: when MkDocs 1.2 is sufficiently common, this can be dropped.
                 log.error(f"Error reading page '{self._autorefs.current_page}':")  # noqa: TRY400
             raise PluginError(f"Could not collect '{identifier}'") from exception
 
         if handler_name not in self._updated_envs:  # We haven't seen this handler before on this document.
-            log.debug("Updating renderer's env")
+            log.debug("Updating handler's rendering env")
             handler._update_env(self.md, self._config)
             self._updated_envs.add(handler_name)
 
@@ -221,11 +213,6 @@ def _process_block(
 
         return rendered, handler, data
 
-    @classmethod
-    @functools.lru_cache(maxsize=None)  # Warn only once
-    def _warn_about_options_key(cls) -> None:
-        log.info("DEPRECATION: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key")
-
 
 class _PostProcessor(Treeprocessor):
     def run(self, root: Element) -> None:

src/mkdocstrings/handlers/__init__.py

@@ -0,0 +1 @@
+"""Handlers module."""