From 0c2aeb376d8243631ce6fe164a78bb5fe400e742 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Tue, 16 Aug 2022 22:02:42 +0200 Subject: [PATCH 1/4] refactor: Report usage-based warnings as user-facing messages The other warnings are developer-facing and should indeed remain as DeprecationWarning. --- src/mkdocstrings/extension.py | 12 +++++++----- src/mkdocstrings/plugin.py | 12 ++++++------ tests/test_extension.py | 12 +++++++----- 3 files changed, 20 insertions(+), 16 deletions(-) diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py index be0c48bb..97363537 100644 --- a/src/mkdocstrings/extension.py +++ b/src/mkdocstrings/extension.py @@ -21,10 +21,10 @@ option_x: etc ``` """ +import functools import re from collections import ChainMap from typing import Any, MutableSequence, Tuple -from warnings import warn from xml.etree.ElementTree import Element import yaml @@ -182,10 +182,7 @@ def _process_block( options = ChainMap(local_options, deprecated_local_options, global_options, deprecated_global_options) if deprecated_global_options or deprecated_local_options: - warn( - "'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key", - DeprecationWarning, - ) + self._warn_about_options_key() if heading_level: options = ChainMap(options, {"heading_level": heading_level}) # like setdefault @@ -216,6 +213,11 @@ def _process_block( return rendered, handler, data + @classmethod + @functools.lru_cache(maxsize=None) # Warn only once + def _warn_about_options_key(cls): + log.info("'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key") + class _PostProcessor(Treeprocessor): def run(self, root: Element): diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py index 34edcc06..3b0afb3c 100644 --- a/src/mkdocstrings/plugin.py +++ b/src/mkdocstrings/plugin.py @@ -19,7 +19,6 @@ from concurrent import futures from typing import Any, BinaryIO, Callable, Iterable, List, Mapping, Optional, Tuple from urllib import request -from warnings import warn from mkdocs.config import Config from mkdocs.config.config_options import Type as MkType @@ -126,11 +125,6 @@ def on_serve(self, server: LiveReloadServer, builder: Callable, **kwargs: Any): **kwargs: Additional arguments passed by MkDocs. """ if self.config["watch"]: - warn( - "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " - "see https://www.mkdocs.org/user-guide/configuration/#watch.", - DeprecationWarning, - ) for element in self.config["watch"]: log.debug(f"Adding directory '{element}' to watcher") server.watch(element, builder) @@ -205,6 +199,12 @@ def on_config(self, config: Config, **kwargs: Any) -> Config: # noqa: W0613 (un self._inv_futures.append(future) inv_loader.shutdown(wait=False) + if self.config["watch"]: + log.info( + "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " + "see https://www.mkdocs.org/user-guide/configuration/#watch", + ) + return config @property diff --git a/tests/test_extension.py b/tests/test_extension.py index df388723..3c41932c 100644 --- a/tests/test_extension.py +++ b/tests/test_extension.py @@ -1,4 +1,5 @@ """Tests for the extension module.""" +import logging import re import sys from textwrap import dedent @@ -31,7 +32,7 @@ def test_multiple_footnotes(ext_markdown): def test_markdown_heading_level(ext_markdown): """Assert that Markdown headings' level doesn't exceed heading_level.""" - output = ext_markdown.convert("::: tests.fixtures.headings\n rendering:\n show_root_heading: true") + output = ext_markdown.convert("::: tests.fixtures.headings\n options:\n show_root_heading: true") assert ">Foo" in output assert ">Bar" in output assert ">Baz" in output @@ -83,7 +84,7 @@ def test_no_double_toc(ext_markdown, expect_permalink): # aa ::: tests.fixtures.headings - rendering: + options: show_root_toc_entry: false # bb @@ -137,10 +138,11 @@ def test_dont_register_every_identifier_as_anchor(plugin): assert identifier not in autorefs._abs_url_map # noqa: WPS437 -def test_use_deprecated_yaml_keys(ext_markdown): +def test_use_deprecated_yaml_keys(ext_markdown, caplog): """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") + caplog.set_level(logging.INFO) + assert "h1" not in ext_markdown.convert("::: tests.fixtures.headings\n rendering:\n heading_level: 2") + assert "single 'options' YAML key" in caplog.text def test_use_new_options_yaml_key(ext_markdown): From 0223ca3c31cbbe8c616866929c8aeb4809fa00a6 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Tue, 16 Aug 2022 22:23:18 +0200 Subject: [PATCH 2/4] Also warn only once --- src/mkdocstrings/plugin.py | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py index 3b0afb3c..e2ce09b9 100644 --- a/src/mkdocstrings/plugin.py +++ b/src/mkdocstrings/plugin.py @@ -200,13 +200,18 @@ def on_config(self, config: Config, **kwargs: Any) -> Config: # noqa: W0613 (un inv_loader.shutdown(wait=False) if self.config["watch"]: - log.info( - "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " - "see https://www.mkdocs.org/user-guide/configuration/#watch", - ) + self._warn_about_watch_option() return config + @classmethod + @functools.lru_cache(maxsize=None) # Warn only once + def _warn_about_watch_option(cls): + log.info( + "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " + "see https://www.mkdocs.org/user-guide/configuration/#watch", + ) + @property def inventory_enabled(self) -> bool: """Tell if the inventory is enabled or not. From 1cad61d19a6c0d3be67a67836cc9eb64aae422ce Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Wed, 17 Aug 2022 18:11:42 +0200 Subject: [PATCH 3/4] lint? --- src/mkdocstrings/plugin.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py index e2ce09b9..24f1cd10 100644 --- a/src/mkdocstrings/plugin.py +++ b/src/mkdocstrings/plugin.py @@ -204,14 +204,6 @@ def on_config(self, config: Config, **kwargs: Any) -> Config: # noqa: W0613 (un return config - @classmethod - @functools.lru_cache(maxsize=None) # Warn only once - def _warn_about_watch_option(cls): - log.info( - "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " - "see https://www.mkdocs.org/user-guide/configuration/#watch", - ) - @property def inventory_enabled(self) -> bool: """Tell if the inventory is enabled or not. @@ -304,3 +296,11 @@ def _load_inventory(cls, loader: InventoryLoaderType, url: str, **kwargs: Any) - result = dict(loader(content, url=url, **kwargs)) log.debug(f"Loaded inventory from {url!r}: {len(result)} items") return result + + @classmethod + @functools.lru_cache(maxsize=None) # Warn only once + def _warn_about_watch_option(cls): + log.info( + "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " + "see https://www.mkdocs.org/user-guide/configuration/#watch", + ) From 1b621f843a1b58942a6a1b7f67e70d3b99ebd158 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sat, 20 Aug 2022 12:37:00 +0200 Subject: [PATCH 4/4] Add 'DEPRECATION:' prefix --- src/mkdocstrings/extension.py | 2 +- src/mkdocstrings/plugin.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py index 97363537..02b94fc9 100644 --- a/src/mkdocstrings/extension.py +++ b/src/mkdocstrings/extension.py @@ -216,7 +216,7 @@ def _process_block( @classmethod @functools.lru_cache(maxsize=None) # Warn only once def _warn_about_options_key(cls): - log.info("'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key") + log.info("DEPRECATION: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key") class _PostProcessor(Treeprocessor): diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py index 24f1cd10..7ec0b85d 100644 --- a/src/mkdocstrings/plugin.py +++ b/src/mkdocstrings/plugin.py @@ -301,6 +301,6 @@ def _load_inventory(cls, loader: InventoryLoaderType, url: str, **kwargs: Any) - @functools.lru_cache(maxsize=None) # Warn only once def _warn_about_watch_option(cls): log.info( - "mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " + "DEPRECATION: mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, " "see https://www.mkdocs.org/user-guide/configuration/#watch", )