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

[oprypin]

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

[pawamoy]

So the rationale is that docs writers are not always developers and won't care about Python warnings? Or even have them disabled? I'm not sure they would care more about an INFO log... 🤔

[oprypin]

1. I think users would care more about an info log compared to literally nothing as it is now - as indeed almost nobody enables warnings.
2. DeprecationWarning means very simply "don't call this function like that". People aren't calling any functions here. There's nothing to learn from a stack trace. Indeed, why is mkdocstrings calling its own deprecated function? That's what DeprecationWarning is saying

[oprypin]

Yet another way to look at it is:
DeprecationWarning means - upgrade everything to latest and if the issue still persists, complain to the developer of the plugin. These cases that I'm changing are incorrectly suggesting this.

[pawamoy]

To me a deprecation warning is not exclusively used for functions. We deprecated using selection and rendering keys, so we inform the users with the standard deprecation mecanisms that they should stop using them, because they will disappear in the next versions and things will break. Users/devs who care about keeping up-to-date dependencies should enable warnings, as best-practice. If they don't and get caught by a breaking change later, that's on them 😕 Though I agree an additional log cannot hurt.

[oprypin]

Do you know any application that informs its users about removing features by emitting a Python DeprecationWarning (which, again, almost nobody will see)?
The fact that this feature removal happens to be implemented by reorganizing some Python code is completely coincidental. Users don't care to see references to Python.
I don't know why you call it a "standard mechanism" in this context when its only purpose is to tell developers to change their Python code in response to some other change. It actually directly says so here https://docs.python.org/3/library/exceptions.html#DeprecationWarning

[oprypin]

Hmm but maybe we could consider just integrating this kind of warning instead https://docs.python.org/3/library/exceptions.html#UserWarning - it even seems to be enabled by default

[oprypin]

Well, it still talks about "user code" so still not a great fit

[oprypin]

https://docs.python.org/3/howto/logging.html#when-to-use-logging also confirms that the expected action in response to Warnings is to change the code of the application. Which doesn't match in these cases that I'm suggesting to change.
I also plan to make this the official guidance of MkDocs.

---

And sorry that I sound so aggressive about this 😞

[oprypin]

And it's not just me either.

https://github.com/mkdocs/mkdocs/blob/0437b7f85380a409244e3b4fabcfb84dccdf6efa/mkdocs/contrib/search/__init__.py#L69-L72

[pawamoy]

Thanks for the links, it seems the DeprecationWarning should not be used for that indeed. How do you feel about prefixing the log line with "DEPRECATION"? I worry users will simply miss/ignore them.

[oprypin]

OK! Why not.

Here's how it will look (first warning is unrelated but nice to see in surrounding)

INFO     -  DeprecationWarning: 'UnescapePostprocessor' is deprecated. This class will be removed in the future; use 'treeprocessors.UnescapeTreeprocessor' instead.
              File "/home/blaxpirit/.local/lib/py/mkdocs_literate_nav/parser.py", line 22, in <module>
                _unescape = markdown.postprocessors.UnescapePostprocessor().run
              File "/home/blaxpirit/.local/lib/py/markdown/util.py", line 103, in deprecated_func
                warnings.warn(
INFO     -  mkdocstrings: DEPRECATION: mkdocstrings' watch feature is deprecated in favor of MkDocs' watch feature, see https://www.mkdocs.org/user-guide/configuration/#watch
INFO     -  Cleaning site directory
INFO     -  mkdocstrings: DEPRECATION: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key
INFO     -  Documentation built in 0.41 seconds
INFO     -  [12:36:10] Watching paths for changes: 'docs', 'mkdocs.yml', 'mkdocs_gen_files'

[pawamoy]

Thanks!