smarie / mkdocs-gallery

Same features as sphinx-gallery (https://sphinx-gallery.github.io/) but on mkdocs (https://www.mkdocs.org/) (no sphinx dependency !).
https://smarie.github.io/mkdocs-gallery
BSD 3-Clause "New" or "Revised" License
38 stars 16 forks source link

DeprecationWarning in mkdocs 1.5.0 for use of mkdocs.utils.warning_filter #89

Open scott-huberty opened 10 months ago

scott-huberty commented 10 months ago

In mkdocs-gallery , mkdocs.utils.warning_filter is used here:

https://github.com/smarie/mkdocs-gallery/blob/cc5c4ad508c03df38c3f58c2c0b8a956d458b900/src/mkdocs_gallery/mkdocs_compatibility.py#L12

At least on mkdocs 1.5. on my computer, calling mkdocs serve will produce a deprecation warning like:

INFO    -  DeprecationWarning: warning_filter doesn't do anything since MkDocs 1.2 and will be removed soon. All messages on the `mkdocs` logger get
           counted automatically.
             File "/Users/shuberty/github_repos/mkdocs-gallery/src/mkdocs_gallery/mkdocs_compatibility.py", line 12, in <module>
               from mkdocs.utils import warning_filter
             File "/Users/shuberty/github_repos/my_envs/my_website/lib/python3.11/site-packages/mkdocs/utils/__init__.py", line 453, in __getattr__
               warnings.warn(

I think we could create a utility function to check the mkdocs version, and if it is greater than 1.2, skip the warnings_filter import.

If this sounds OK I can open up a PR to fix the issue.

EDIT:

I forgot to mention, here are my versions for the relevant packages:

mkdocs: 1.5.3
mkdocs-material: 9.5.2
mkdocs-gallery: 0.1dev
scott-huberty commented 10 months ago

On a second thought, Since warning_filter has been a no-op since 1.2 (released two years ago), a second option would be to simply remove the use of warning_filter in mkdocs_gallery, assuming that it won't be useful for the vast majority of people, and replace it with the recommended logging plugin:

from the 1.2 release notes:

The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins should remove any reference to is as it may be deleted in a future release. To ensure any warnings get counted, simply log them to the mkdocs log (i.e.: mkdocs.plugins.pluginname).