Deprecate after Material 9.4 Releases

[facelessuser]

We've long felt that this work should live in the MkDocs Material repo, but we provided it as a courtesy as Material was uncomfortable maintaining this extension.

With the upcoming release of MkDocs Material 9.4, the maintainer now feels confident enough to maintain this extension. Once this release is made, and everything has been confirmed to have 1:1 behavior, we will deprecate this extension and generate a warning to use the Material's version.

This is a much better arrangement moving forward as Material will have all the "Material" support baked in and we can focus on Pymdown Extensions.

[squidfunk]

9.4.0 is out! Thanks for maintaining the extension for the last years. I'll take it from here ☺️

[squidfunk]

@facelessuser did you have a chance to look at this? We could deprecate the extension and remove it in the next major release. I think a deprecation notice when somebody is referencing the extension in mkdocs.yml should be sufficient.

[facelessuser]

I can probably make it a priority. I didn't know how fast you were wanting to move with this. I can up the priority of this and get it out soonish.

[squidfunk]

I don't want to pressure you, just wanted to know whether you're still considering this. The deprecation notice is mandatory for us to incentivize people to move to the new extension, and we better have a long deprecation period, because I suspect that many people are using it. After a sufficiently long deprecation period, we will remove the extension.

[facelessuser]

Yep still planning it, just hadn't done it yet. Makes sense to do it sooner rather than later.

[facelessuser]

I've created a PR. I need to test it locally before merging, but it should resolve this issue.

[squidfunk]

I just tried it, and the deprecation is shown:

INFO    -  DeprecationWarning: Using emoji indexes with no arguments is now deprecated.
           Emoji indexes now take 2 arguments: 'options' and 'md'.
           Please update your custom index accordingly.

             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/pymdownx/emoji.py", line 251, in
           _set_index
               util.warn_deprecated(MSG_INDEX_WARN)
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/pymdownx/util.py", line 328, in
           warn_deprecated
               warnings.warn(
INFO    -  DeprecationWarning: 'twemoji' is deprecated.
           Material emoji logic has been officially moved into mkdocs-material
           version 9.4. Please use Material's 'material.extensions.emoji.twemoji' as mkdocs_material_extensions
           is deprecated and will no longer be supported moving forward. This
           is the last release.

             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/pymdownx/emoji.py", line 252, in
           _set_index
               self.emoji_index = index()
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/materialx/emoji.py", line 57, in
           _deprecated_func
               warnings.warn(
ERROR   -  Config value 'markdown_extensions': Failed to load extension 'pymdownx.emoji'.
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/mkdocs/config/config_options.py", line
           1021, in run_validation
               md.registerExtensions((ext,), self.configdata)
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/markdown/core.py", line 115, in
           registerExtensions
               ext.extendMarkdown(self)
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/pymdownx/emoji.py", line 393, in
           extendMarkdown
               md.inlinePatterns.register(EmojiPattern(RE_EMOJI, config, md), "emoji", 75)
                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/pymdownx/emoji.py", line 238, in
           __init__
               self._set_index(config["emoji_index"])
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/pymdownx/emoji.py", line 252, in
           _set_index
               self.emoji_index = index()
                                  ^^^^^^^
             File "/Users/squidfunk/.workspace/squidfunk/repos/mkdocs-material/community/venv/lib/python3.11/site-packages/materialx/emoji.py", line 62, in
           _deprecated_func
               return func(*args, **kwargs)
                      ^^^^^^^^^^^^^^^^^^^^^
           TypeError: twemoji() missing 2 required positional arguments: 'options' and 'md'

Aborted with 1 configuration errors!

However, an error is triggered. The error is only triggered when both emoji_generator and emoji_index are set to materialx (our recommended setting). When I set emoji_indexto pymdownx.*, the error does not appear. Not sure why I'm observing this. Let me know if you need a minimal reproduction for this.

I installed as follows:

pip install git+https://github.com/facelessuser/mkdocs-material-extensions.git@chore/deprecate

[facelessuser]

Yeah, I reworked the deprecation approach, tests should be passing now.

[squidfunk]

Jup, the error is gone! You are fast 😎

[facelessuser]

Does it apply warnings as expected? I haven't run it in a project yet.

[facelessuser]

Hmm. Doesn't seem it bubbles up.

[facelessuser]

I may have to force some mkdocs logging...

[squidfunk]

It emits on INFO level, if you mean that. I've seen this for other deprecation warnings as well. Do you want to emit a warning? That would break strict mode, which would be perfect because it would accelerate adoption.

[facelessuser]

No, it's just not generating for me in the project I'm testing it in.

[facelessuser]

I don't think MkDocs logs random deprecation warnings from the Python Markdown level. We'd have to somehow send a message to the MkDocs logger.

[facelessuser]

I can tap into the MkDocs logging. I just need to approach it from an angle where we don't spam the warning on every file.

[squidfunk]

Ok, great!

[facelessuser]

Logging will be a warning and should only be emitted once for each function.

WARNING -   Material emoji logic has been officially moved into mkdocs-material
           version 9.4. Please use Material's 'material.extensions.emoji.twemoji' as mkdocs_material_extensions
           is deprecated and will no longer be supported moving forward. This
           is the last release.
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/facelessuser/Code/github/coloraide/site
WARNING -   Material emoji logic has been officially moved into mkdocs-material
           version 9.4. Please use Material's 'material.extensions.emoji.to_svg' as mkdocs_material_extensions
           is deprecated and will no longer be supported moving forward. This
           is the last release.
INFO    -  Documentation built in 20.58 seconds

[squidfunk]

Perfect! Glad you solved it. I will bump the minimum required version to 1.3 once it is out.

[facelessuser]

I imagine I can get it out later this evening (my time).

[facelessuser]

Released

[squidfunk]

Thanks! I just bumped to 1.3 and can confirm that it works! Thanks again for maintaining this project for such a long time!