diff --git a/mkdocs.yml b/mkdocs.yml index 572d771d..3a82fccf 100644 --- a/mkdocs.yml +++ b/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: diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py index 3b0e54fb..78d30165 100644 --- a/src/mkdocstrings/extension.py +++ b/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( diff --git a/tests/test_extension.py b/tests/test_extension.py index 8039e240..df388723 100644 --- a/tests/test_extension.py +++ b/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")