@@ -705,11 +705,28 @@ 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. This will
710- only have effect on things drawn after this function is called.
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`
726+
711727
712- For best results, the "xkcd script" font should be installed: it is
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
713730 not included with Matplotlib.
714731
715732 Parameters