refactor: Report usage-based warnings as user-facing messages

The other warnings are developer-facing and should indeed remain as DeprecationWarning.

PR #464: #464

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("DEPRECATION: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key")
+
 
 class _PostProcessor(Treeprocessor):
     def run(self, root: Element):

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,9 @@ 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"]:
+            self._warn_about_watch_option()
+
         return config
 
     @property
@@ -299,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(
+            "DEPRECATION: mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, "
+            "see https://www.mkdocs.org/user-guide/configuration/#watch",
+        )

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</h3>" in output
     assert ">Bar</h5>" in output
     assert ">Baz</h6>" 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):