matplotlib
diff --git a/‎lib/matplotlib/pyplot.py
Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+21-5Lines changed: 21 additions & 5 deletions b/‎lib/matplotlib/pyplot.py
Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+21-5Lines changed: 21 additions & 5 deletions
@@ -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
     ----------