From c812912eabd3a767c8e7b5bdff7de7cdf5169fc1 Mon Sep 17 00:00:00 2001
From: Oleh Prypin <oleh@pryp.in>
Date: Tue, 16 Aug 2022 22:02:42 +0200
Subject: [PATCH] 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    | 11 ++++++-----
 2 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/src/mkdocstrings/extension.py b/src/mkdocstrings/extension.py
index be0c48bb..a48ac894 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
 
+    @staticmethod
+    @functools.lru_cache(maxsize=None)
+    def _warn_about_options_key():
+        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..0d2805cd 100644
--- a/src/mkdocstrings/plugin.py
+++ b/src/mkdocstrings/plugin.py
@@ -126,11 +126,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 +200,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