@@ -705,13 +705,29 @@ def setp(obj, *args, **kwargs):
705705def xkcd (
706706scale :float = 1 ,length :float = 100 ,randomness :float = 2
707707)-> ExitStack :
708- """
709- Turn on `xkcd <https://xkcd.com/>`_ sketch-style drawing mode.
708+ r"""
709+ [*Discouraged*] Turn on `xkcd <https://xkcd.com/>`_ sketch-style drawing mode.
710+
711+ .. admonition:: Discouraged
712+
713+ The use of ``plt.xkcd()`` is discouraged; instead use
714+ the ``xkcd`` style sheet::
715+
716+ plt.style.use('xkcd')
717+ with plt.style.use('xkcd'):
718+
719+ Instead of passing in arguments, modify the ``rcParam``::
720+
721+ import matplotlib as mpl
722+
723+ mpl.rcParams['path.sketch'] = (scale, length, randomness)
724+
725+ For more information, see :ref:`customizing`
710726
711- This will only have an effect on things drawn after this function is called.
712727
713- For best results, install the `xkcd script <https://github.com/ipython/xkcd-font/>`_
714- font; xkcd fonts are not packaged with Matplotlib.
728+ This drawing mode only affects things drawn after this function is called.
729+ For best results, the "xkcd script" font should be installed; it is
730+ not included with Matplotlib.
715731
716732 Parameters
717733 ----------