add discouraged admonishment to plt.xkcd

story645 · story645 · commit b19d0e1dee02 · 2023-11-13T18:46:36.000-05:00
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -705,11 +705,28 @@ 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.  This will
-    only have effect on things drawn after this function is called.
+    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`
+
 
-    For best results, the "xkcd script" font should be installed: it is
+    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
