refactor: Deprecate 'selection' and 'rendering' YAML keys

As seen in commit eb822cb, the separation of
the selection/collection and rendering configuration
is problematic. This commit further reduces this
separation by merging the two current YAML keys
'selection' and 'rendering' into a single
'options' key. It means both the 'collect' and
'render' methods have access to every option.

The old keys can still be used, but are deprecated,
and therefore a deprecation warning is emitted
if these keys are found in either global or local
configurations.

PR #420: #420

mkdocs.yml

@@ -91,11 +91,10 @@ plugins:
         - https://docs.python.org/3/objects.inv
         - https://docs.python-requests.org/en/master/objects.inv  # demonstration purpose in the docs
         - https://mkdocstrings.github.io/autorefs/objects.inv
-        selection:
+        options:
           docstring_style: google
           docstring_options:
             ignore_init_summary: yes
-        rendering:
           merge_init_into_class: yes
           show_submodules: no
     watch:

src/mkdocstrings/extension.py

@@ -24,6 +24,7 @@
 import re
 from collections import ChainMap
 from typing import Any, Mapping, MutableMapping, MutableSequence, Tuple
+from warnings import warn
 from xml.etree.ElementTree import Element
 
 import yaml
@@ -173,13 +174,21 @@ def _process_block(
         handler_config = self._handlers.get_handler_config(handler_name)
         handler = self._handlers.get_handler(handler_name, handler_config)
 
-        selection, rendering = get_item_configs(handler_config, config)
+        options = ChainMap(config.get("options", {}), handler_config.get("options", {}))
+        if not options:
+            selection, rendering = get_item_configs(handler_config, config)
+            if selection or rendering:
+                warn(
+                    "'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key",
+                    DeprecationWarning,
+                )
+                options = ChainMap(*selection.maps, *rendering.maps)  # type: ignore[attr-defined]
         if heading_level:
-            rendering = ChainMap(rendering, {"heading_level": heading_level})  # like setdefault
+            options = ChainMap(options, {"heading_level": heading_level})  # like setdefault
 
         log.debug("Collecting data")
         try:
-            data: CollectorItem = handler.collect(identifier, selection)
+            data: CollectorItem = handler.collect(identifier, options)
         except CollectionError as exception:
             log.error(str(exception))
             if PluginError is SystemExit:  # When MkDocs 1.2 is sufficiently common, this can be dropped.
@@ -193,7 +202,7 @@ def _process_block(
 
         log.debug("Rendering templates")
         try:
-            rendered = handler.render(data, rendering)
+            rendered = handler.render(data, options)
         except TemplateNotFound as exc:
             theme_name = self._config["theme_name"]
             log.error(

tests/test_extension.py

@@ -135,3 +135,15 @@ def test_dont_register_every_identifier_as_anchor(plugin):
     for identifier in ids:
         assert identifier not in autorefs._url_map  # noqa: WPS437
         assert identifier not in autorefs._abs_url_map  # noqa: WPS437
+
+
+def test_use_deprecated_yaml_keys(ext_markdown):
+    """Check that using the deprecated 'selection' and 'rendering' YAML keys emits a deprecation warning."""
+    with pytest.warns(DeprecationWarning, match="single 'options' YAML key"):
+        assert "h1" not in ext_markdown.convert("::: tests.fixtures.headings\n    rendering:\n      heading_level: 2")
+
+
+def test_use_new_options_yaml_key(ext_markdown):
+    """Check that using the new 'options' YAML key works as expected."""
+    assert "h1" in ext_markdown.convert("::: tests.fixtures.headings\n    options:\n      heading_level: 1")
+    assert "h1" not in ext_markdown.convert("::: tests.fixtures.headings\n    options:\n      heading_level: 2")