From 5f5cb80eb04d7b64c36ddba048af980f4778daa1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 10 Apr 2022 14:14:01 +0200 Subject: [PATCH 1/2] 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. --- mkdocs.yml | 3 +-- src/mkdocstrings/extension.py | 17 +++++++++++++---- tests/test_extension.py | 12 ++++++++++++ 3 files changed, 26 insertions(+), 6 deletions(-) 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..3a249256 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): + 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") From abaa11a16750194b70bcfd4b08ad256973bacab8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sun, 10 Apr 2022 14:25:53 +0200 Subject: [PATCH 2/2] fixup! refactor: Deprecate 'selection' and 'rendering' YAML keys --- tests/test_extension.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_extension.py b/tests/test_extension.py index 3a249256..df388723 100644 --- a/tests/test_extension.py +++ b/tests/test_extension.py @@ -139,8 +139,8 @@ def test_dont_register_every_identifier_as_anchor(plugin): 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): - ext_markdown.convert("::: tests.fixtures.headings\n rendering:\n heading_level: 2") + 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):