While investigating mkdocstrings/mkdocstrings#676, I noticed that:

• mkdocs serve always catches deprecation warnings and re-emits them as INFO logs
• python -m mkdocs serve always ignores them completely

...whatever the value of PYTHONWARNINGS or the -W flag.

Looking at the docs (https://docs.python.org/3/library/warnings.html#overriding-the-default-filter), it looks like it's possible to override the default filter only when warning options were not passed with -W or PYTHONWARNINGS, using if not sys.warnoptions.

This would allow end users to control whether deprecation warnings are shown in the logs, or whether they should make the command fail instead. Well, this would allow the usual warnings management provided by Python and the standard lib.

May I suggest that we do this in MkDocs? It would happen in mkdocs.__main__._enable_warnings. I tried it locally and it works 🙂 Can send a PR if other maintainers agree on the change:

def _enable_warnings():
    if not sys.warnoptions:
        from mkdocs.commands import build

        build.log.addFilter(utils.DuplicateFilter())

        warnings.simplefilter('module', DeprecationWarning)
        warnings.showwarning = _showwarning