Deprecate the library

Resolves #27

README.md

@@ -6,6 +6,11 @@
 ![License][license-image-mit]
 # MkDocs Material Extensions
 
+> NOTE: This project is now deprecated as MkDocs for Material now implements this logic directly.
+> Users should migrate to using `mkdocs-material`'s `material.extensions.emoji.twemoji` and 
+> `material.extensions.emoji.to_svg` in place of the respective `materialx.emoji.twemoji` and `materialx.emoji.to_svg`
+> functions provided by this library.
+
 Markdown extension resources for [MkDocs for Material][mkdocs-material]
 
 ## Install

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.3
+
+- **NEW**: The final release. `mkdocs-material` (version 9.4) now has this library's logic built-in making this library
+  obsolete. Users should migrate to using `mkdocs-material`'s `material.extensions.emoji.twemoji` and
+  `material.extensions.emoji.to_svg` in place of the respective `materialx.emoji.twemoji` and `materialx.emoji.to_svg`
+  functions.
+
 ## 1.2
 
 - **NEW**: Add official support for Python 3.11 and 3.12.

materialx/__meta__.py

@@ -188,5 +188,5 @@ def parse_version(ver):
     return Version(major, minor, micro, release, pre, post, dev)
 
 
-__version_info__ = Version(1, 2, 0, "final")
+__version_info__ = Version(1, 3, 0, "final")
 __version__ = __version_info__._get_canonical()

materialx/emoji.py

@@ -13,6 +13,16 @@
 import pymdownx
 from pymdownx.emoji import TWEMOJI_SVG_CDN, add_attriubtes
 import xml.etree.ElementTree as etree  # noqa: N813
+import warnings
+from functools import wraps
+
+DEPRECATED = """
+Material emoji logic has been officially moved into mkdocs-material
+version 9.4. Please use Material's '{}' as mkdocs_material_extensions
+is deprecated and will no longer be supported moving forward. This
+is the last release.
+"""
+
 
 OPTION_SUPPORT = pymdownx.__version_info__ >= (7, 1, 0)
 RESOURCES = os.path.dirname(inspect.getfile(material))
@@ -30,6 +40,30 @@ def _patch_index(options):
     return _patch_index_for_locations(tuple(icon_locations))
 
 
+def deprecated(message, stacklevel=2):  # pragma: no cover
+    """
+    Raise a `DeprecationWarning` when wrapped function/method is called.
+
+    Usage:
+
+        @deprecated("This method will be removed in version X; use Y instead.")
+        def some_method()"
+            pass
+    """
+
+    def _wrapper(func):
+        @wraps(func)
+        def _deprecated_func(*args, **kwargs):
+            warnings.warn(
+                f"'{func.__name__}' is deprecated. {message}",
+                category=DeprecationWarning,
+                stacklevel=stacklevel
+            )
+            return func(*args, **kwargs)
+        return _deprecated_func
+    return _wrapper
+
+
 @functools.lru_cache(maxsize=None)
 def _patch_index_for_locations(icon_locations):
     import pymdownx.twemoji_db as twemoji_db
@@ -53,18 +87,21 @@ def _patch_index_for_locations(icon_locations):
 
 
 if OPTION_SUPPORT:  # pragma: no cover
+    @deprecated(DEPRECATED.format('material.extensions.emoji.twemoji'))
     def twemoji(options, md):
         """Provide a copied Twemoji index with additional codes for Material included icons."""
 
         return _patch_index(options)
 
 else:  # pragma: no cover
+    @deprecated(DEPRECATED.format('material.extensions.emoji.twemoji'))
     def twemoji():
         """Provide a copied Twemoji index with additional codes for Material included icons."""
 
         return _patch_index({})
 
 
+@deprecated(DEPRECATED.format('material.extensions.emoji.to_svg'))
 def to_svg(index, shortname, alias, uc, alt, title, category, options, md):
     """Return SVG element."""