Emit INFO instead of WARNING for Deprecated options

[kcgthb]

Hi!

Currently, the Deprecated helper emits a WARNING message when a deprecated option is used, which breaks building sites in strict mode.

This is causing an issue with MkDocs Material, where a deprecated option is still useful in some cases (see a full description in https://github.com/squidfunk/mkdocs-material/issues/7146).

On @squidfunk's suggestion, would it be possible to consider emitting an INFO message instead of a WARNING when Deprecated is used, a bit like it was done in #2907?

Thanks!

[pawamoy]

Hi @kcgthb, thanks for opening this issue :)

I have read the discussion in Material for MkDocs' repository, and to me it would make sense to let users decide whether to emit info or warning messages for plugin configs using the Deprecated API, just like pytest users can decide whether to treat actual warnings as info messages or errors.

I recently added a breaking change in mkdocstrings-python, with a deprecation period where users will first get info logs (not breaking their strict builds), then warnings (now breaking them).

Back to this issue, I wonder though if we should allow setting info level globally, or per deprecation message.

[kcgthb]

I :100: agree that allowing users to choose the message level (INFO or WARNING) for each Deprecated object would be even better!

[squidfunk]

@tomchristie 👋 in my view, this issue is a great start for improving MkDocs, as it touches many users. Basically, when you're using --strict mode, your build will fail if you run into a plugin deprecation, but not when you use something that was deprecated in MkDocs. That sounds like an inconsistency, also see https://github.com/squidfunk/mkdocs-material/issues/7146#issuecomment-2092364939.

It would be great if you could share your view ☺️

[tomchristie]

but not when you use something that was deprecated in MkDocs

Could you expand on that?

The first part "when you're using --strict mode, your build will fail if you run into a plugin deprecation" seems right, sounds like it's the inconsistency that needs addressing?

[squidfunk]

I did expand on it in the comment I linked: https://github.com/squidfunk/mkdocs-material/issues/7146#issuecomment-2092364939

IMHO, the most sensical thing would be that the Deprecated helper emits something like the following, which are deprecation warnings we fixed when upgrading to 1.6, as was reported in https://github.com/squidfunk/mkdocs-material/issues/7119#issuecomment-2081713974:

INFO    -  DeprecationWarning: Do not access Theme._vars, instead access the keys of Theme directly.
             File "/opt/homebrew/lib/python3.10/site-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 82, in on_config
               theme_locale = custom_theme._vars.get("locale")
             File "/opt/homebrew/lib/python3.10/site-packages/mkdocs/theme.py", line 87, in _vars
               warnings.warn(
INFO    -  DeprecationWarning: To replace an existing file, call `remove` before `append`.
             File "<snip>/mkdocs-material/material/plugins/privacy/plugin.py", line 445, in _queue
               self.assets.append(file)
             File "/opt/homebrew/lib/python3.10/site-packages/mkdocs/structure/files.py", line 100, in append
               warnings.warn(

MkDocs uses this approach itself for their internal APIs, e.g., the Files collections, see an example, but emit warnings for plugin configurations. IMHO, this is inconsistent, so before we act here, we should discuss this with the maintainers of MkDocs. Interestingly, the aforementioned DeprecationWarnings were formerly also raised with level WARNING and de-escalated to INFO in a subsequent release.