add discouraged admonishment to plt.xkcd

story645 · story645 · commit 0c9af391e9a3 · 2023-12-01T14:31:22.000-05:00
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -705,13 +705,29 @@ def setp(obj, *args, **kwargs):
 def xkcd(
     scale: float = 1, length: float = 100, randomness: float = 2
 ) -> ExitStack:
-    """
-    Turn on `xkcd <https://xkcd.com/>`_ sketch-style drawing mode.
+    r"""
+    [*Discouraged*] Turn on `xkcd <https://xkcd.com/>`_ sketch-style drawing mode.
+
+    .. admonition:: Discouraged
+
+        The use of ``plt.xkcd()`` is discouraged; instead use
+        the ``xkcd`` style sheet::
+
+            plt.style.use('xkcd')
+            with plt.style.use('xkcd'):
+
+        Instead of passing in arguments, modify the ``rcParam``::
+
+            import matplotlib as mpl
+
+            mpl.rcParams['path.sketch'] = (scale, length, randomness)
+
+        For more information, see :ref:`customizing`
 
-    This will only have an effect on things drawn after this function is called.
 
-    For best results, install the `xkcd script <https://github.com/ipython/xkcd-font/>`_
-    font; xkcd fonts are not packaged with Matplotlib.
+    This drawing mode only affects things drawn after this function is called.
+    For best results, the "xkcd script" font should be installed; it is
+    not included with Matplotlib.
 
     Parameters
     ----------
