Some manual fixes.

anntzer · May 29, 2018 · May 25, 2018 · May 27, 2018 · May 29, 2018 · 844b28cdd41ef2d6a72e4c768b592a26b06132a2
commit 844b28cdd41ef2d6a72e4c768b592a26b06132a2
diff --git a/examples/color/color_cycle_default.py b/examples/color/color_cycle_default.py
@@ -4,7 +4,7 @@
 ====================================
 
 Display the colors from the default prop_cycle, which is obtained from the
-:ref:`rc parameters</tutorials/introductory/customizing>`.
+:doc:`rc parameters</tutorials/introductory/customizing>`.
 """
 import numpy as np
 import matplotlib.pyplot as plt

diff --git a/examples/color/color_cycler.py b/examples/color/color_cycler.py
@@ -8,11 +8,10 @@
 
 This example demonstrates two different APIs:
 
-    1. Setting the default 
-       :doc:`rc parameter</tutorials/introductory/customizing>`
-       specifying the property cycle. This affects all subsequent axes
-       (but not axes already created).
-    2. Setting the property cycle for a single pair of axes.
+1. Setting the default :doc:`rc parameter</tutorials/introductory/customizing>`
+   specifying the property cycle. This affects all subsequent axes (but not
+   axes already created).
+2. Setting the property cycle for a single pair of axes.
 """
 from cycler import cycler
 import numpy as np

diff --git a/examples/images_contours_and_fields/contour_demo.py b/examples/images_contours_and_fields/contour_demo.py
@@ -6,8 +6,7 @@
 Illustrate simple contour plotting, contours on an image with
 a colorbar for the contours, and labelled contours.
 
-See also the
-:ref:`contour image example
+See also the :doc:`contour image example
 </gallery/images_contours_and_fields/contour_image>`.
 """
 import matplotlib

diff --git a/examples/images_contours_and_fields/contour_image.py b/examples/images_contours_and_fields/contour_image.py
@@ -4,16 +4,14 @@
 =============
 
 Test combinations of contouring, filled contouring, and image plotting.
-For contour labelling, see See also the
-:ref:`contour demo example
+For contour labelling, see also the :doc:`contour demo example
 </gallery/images_contours_and_fields/contour_demo>`.
 
 The emphasis in this demo is on showing how to make contours register
-correctly on images, and on how to get both of them oriented as
-desired.  In particular, note the usage of the 
-:ref:`"origin" and "extent"
-</tutorials/intermediate/imshow_extent>`
-keyword arguments to imshow and contour.
+correctly on images, and on how to get both of them oriented as desired.
+In particular, note the usage of the :doc:`"origin" and "extent"
+</tutorials/intermediate/imshow_extent>` keyword arguments to imshow and
+contour.
 """
 import matplotlib.pyplot as plt
 import numpy as np

diff --git a/examples/images_contours_and_fields/contour_label_demo.py b/examples/images_contours_and_fields/contour_label_demo.py
@@ -6,7 +6,7 @@
 Illustrate some of the more advanced things that one can do with
 contour labels.
 
-See also the :ref:`contour demo example
+See also the :doc:`contour demo example
 </gallery/images_contours_and_fields/contour_demo>`.
 """
 

diff --git a/examples/images_contours_and_fields/image_demo.py b/examples/images_contours_and_fields/image_demo.py
@@ -137,7 +137,7 @@
 # x[0,0] in the upper left or lower right by using the origin parameter.
 # You can also control the default setting image.origin in your
 # :ref:`matplotlibrc file <customizing-with-matplotlibrc-files>`. For more on
-# this topic see the :ref:`complete guide on origin and extent
+# this topic see the :doc:`complete guide on origin and extent
 # </tutorials/intermediate/imshow_extent>`.
 
 x = np.arange(120).reshape((10, 12))

diff --git a/examples/images_contours_and_fields/quiver_demo.py b/examples/images_contours_and_fields/quiver_demo.py
@@ -3,14 +3,13 @@
 Demonstration of advanced quiver and quiverkey functions
 ========================================================
 
-Demonstrates some more advanced options for `~.axes.Axes.quiver`. 
-For a simple example refer to 
-:doc:`/gallery/images_contours_and_fields/quiver_simple_demo`.
+Demonstrates some more advanced options for `~.axes.Axes.quiver`.  For a simple
+example refer to :doc:`/gallery/images_contours_and_fields/quiver_simple_demo`.
 
-Known problem: the plot autoscaling does not take into account
-the arrows, so those on the boundaries are often out of the picture.
-This is *not* an easy problem to solve in a perfectly general way.
-The workaround is to manually expand the Axes objects.
+Known problem: the plot autoscaling does not take into account the arrows, so
+those on the boundaries are often out of the picture.  This is *not* an easy
+problem to solve in a perfectly general way.  The workaround is to manually
+expand the Axes objects.
 """
 import matplotlib.pyplot as plt
 import numpy as np

diff --git a/examples/images_contours_and_fields/quiver_simple_demo.py b/examples/images_contours_and_fields/quiver_simple_demo.py
@@ -3,10 +3,9 @@
 Quiver Simple Demo
 ==================
 
-A simple example of a `~.axes.Axes.quiver` plot with a
-`~.axes.Axes.quiverkey`.
+A simple example of a `~.axes.Axes.quiver` plot with a `~.axes.Axes.quiverkey`.
 
-For more advanced options refer to 
+For more advanced options refer to
 :doc:`/gallery/images_contours_and_fields/quiver_demo`.
 """
 import matplotlib.pyplot as plt

diff --git a/examples/shapes_and_collections/ellipse_demo.py b/examples/shapes_and_collections/ellipse_demo.py
@@ -4,7 +4,7 @@
 ============
 
 Draw many ellipses. Here individual ellipses are drawn. Compare this
-to the :ref:`Ellipse collection example
+to the :doc:`Ellipse collection example
 </gallery/shapes_and_collections/ellipse_collection>`.
 """
 import matplotlib.pyplot as plt

diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -4,23 +4,21 @@
 
 .. important::
 
-    It is unlikely that you would ever create a Legend instance manually.
-    Most users would normally create a legend via the
+    It is unlikely that you would ever create a Legend instance
+    manually.  Most users would normally create a legend via the
     :meth:`~matplotlib.axes.Axes.legend` function. For more details on legends
-    there is also a :ref:`legend guide
-    </tutorials/intermediate/legend_guide>`.
-
-The Legend class can be considered as a container of legend handles
-and legend texts. Creation of corresponding legend handles from the
-plot elements in the axes or figures (e.g., lines, patches, etc.) are
-specified by the handler map, which defines the mapping between the
-plot elements and the legend handlers to be used (the default legend
-handlers are defined in the :mod:`~matplotlib.legend_handler` module).
-Note that not all kinds of artist are supported by the legend yet by default
-but it is possible to extend the legend handler's capabilities to support
-arbitrary objects. See the :ref:`legend guide
-</tutorials/intermediate/legend_guide>` for more information.
-
+    there is also a :doc:`legend guide </tutorials/intermediate/legend_guide>`.
+
+The Legend class can be considered as a container of legend handles and
+legend texts. Creation of corresponding legend handles from the plot elements
+in the axes or figures (e.g., lines, patches, etc.) are specified by the
+handler map, which defines the mapping between the plot elements and the
+legend handlers to be used (the default legend handlers are defined in the
+:mod:`~matplotlib.legend_handler` module).  Note that not all kinds of
+artist are supported by the legend yet by default but it is possible to
+extend the legend handler's capabilities to support arbitrary objects. See
+the :doc:`legend guide </tutorials/intermediate/legend_guide>` for more
+information.
 """
 
 import logging

diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -1,7 +1,7 @@
 """
 This module defines default legend handlers.
 
-It is strongly encouraged to have read the :ref:`legend guide
+It is strongly encouraged to have read the :doc:`legend guide
 </tutorials/intermediate/legend_guide>` before this documentation.
 
 Legend handlers are expected to be a callable object with a following

diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -2574,7 +2574,7 @@ class PolygonSelector(_SelectorWidget):
         if the mouse click is within `vertex_select_radius` pixels of the
         vertex. The default radius is 15 pixels.
 
-    See Also
+    Examples
     --------
     :doc:`/gallery/widgets/polygon_selector_demo`
     """

diff --git a/tutorials/introductory/lifecycle.py b/tutorials/introductory/lifecycle.py
@@ -23,11 +23,10 @@
 interface. In this case, we utilize an instance of :class:`axes.Axes`
 in order to render visualizations on an instance of :class:`figure.Figure`.
 
-The second is based on MATLAB and uses
-a state-based interface. This is encapsulated in the :mod:`pyplot`
-module. See the :ref:`pyplot tutorials
-</tutorials/introductory/pyplot>`
-for a more in-depth look at the pyplot interface.
+The second is based on MATLAB and uses a state-based interface. This is
+encapsulated in the :mod:`pyplot` module. See the :doc:`pyplot tutorials
+</tutorials/introductory/pyplot>` for a more in-depth look at the pyplot
+interface.
 
 Most of the terms are straightforward but the main thing to remember
 is that:
@@ -85,7 +84,7 @@
 # .. note::
 #
 #    Figures can have multiple axes on them. For information on how to do this,
-#    see the :ref:`Tight Layout tutorial
+#    see the :doc:`Tight Layout tutorial
 #    </tutorials/intermediate/tight_layout_guide>`.
 
 fig, ax = plt.subplots()

diff --git a/tutorials/text/mathtext.py b/tutorials/text/mathtext.py
@@ -63,7 +63,7 @@
 #
 #    have special meaning outside of math mode in TeX.  Therefore, these
 #    characters will behave differently depending on the rcParam
-#    ``text.usetex`` flag.  See the :ref:`usetex tutorial
+#    ``text.usetex`` flag.  See the :doc:`usetex tutorial
 #    </tutorials/text/usetex>` for more information.
 #
 # Subscripts and superscripts

diff --git a/tutorials/text/text_props.py b/tutorials/text/text_props.py
@@ -217,7 +217,7 @@
 #    font.sans-serif: Source Han Sans TW, Arial, sans-serif
 #
 # To control the font used on per-artist basis use the ``'name'``,
-# ``'fontname'`` or ``'fontproperties'`` kwargs documented :ref:`above
+# ``'fontname'`` or ``'fontproperties'`` kwargs documented :doc:`above
 # </tutorials/text/text_props>`.
 #
 #

diff --git a/tutorials/text/usetex.py b/tutorials/text/usetex.py
@@ -12,21 +12,21 @@
 * PS
 * PDF
 
-The LaTeX option is activated by setting ``text.usetex : True`` in
-your rc settings.  Text handling with matplotlib's LaTeX support is
-slower than matplotlib's very capable :ref:`mathtext
-</tutorials/text/mathtext>`, but is more flexible, since different LaTeX
-packages (font packages, math packages, etc.)  can be used. The
-results can be striking, especially when you take care to use the same
-fonts in your figures as in the main document.
+The LaTeX option is activated by setting ``text.usetex : True`` in your rc
+settings.  Text handling with matplotlib's LaTeX support is slower than
+matplotlib's very capable :doc:`mathtext </tutorials/text/mathtext>`, but is
+more flexible, since different LaTeX packages (font packages, math packages,
+etc.) can be used. The results can be striking, especially when you take care
+to use the same fonts in your figures as in the main document.
 
 Matplotlib's LaTeX support requires a working LaTeX_ installation, dvipng_
 (which may be included with your LaTeX installation), and Ghostscript_
 (GPL Ghostscript 8.60 or later is recommended). The executables for these
 external dependencies must all be located on your :envvar:`PATH`.
 
-There are a couple of options to mention, which can be changed using :ref:`rc
-settings </tutorials/introductory/customizing>`. Here is an example matplotlibrc file::
+There are a couple of options to mention, which can be changed using
+:doc:`rc settings </tutorials/introductory/customizing>`. Here is an example
+matplotlibrc file::
 
   font.family        : serif
   font.serif         : Times, Palatino, New Century Schoolbook, Bookman, Computer Modern Roman