matplotlib · anntzer · Aug 18, 2019 · Aug 17, 2019
diff --git a/doc/api/prev_api_changes/api_changes_1.2.x.rst b/doc/api/prev_api_changes/api_changes_1.2.x.rst
@@ -4,16 +4,16 @@ Changes in 1.2.x
 * The ``classic`` option of the rc parameter ``toolbar`` is deprecated
   and will be removed in the next release.
 
-* The :meth:`~matplotlib.cbook.isvector` method has been removed since it
+* The ``matplotlib.cbook.isvector`` method has been removed since it
   is no longer functional.
 
-* The `rasterization_zorder` property on `~matplotlib.axes.Axes` a
+* The ``rasterization_zorder`` property on `~matplotlib.axes.Axes` sets a
   zorder below which artists are rasterized.  This has defaulted to
-  -30000.0, but it now defaults to `None`, meaning no artists will be
+  -30000.0, but it now defaults to *None*, meaning no artists will be
   rasterized.  In order to rasterize artists below a given zorder
-  value, `set_rasterization_zorder` must be explicitly called.
+  value, `.set_rasterization_zorder` must be explicitly called.
 
-* In :meth:`~matplotlib.axes.Axes.scatter`, and `~pyplot.scatter`,
+* In :meth:`~matplotlib.axes.Axes.scatter`, and `~.pyplot.scatter`,
   when specifying a marker using a tuple, the angle is now specified
   in degrees, not radians.
 
@@ -35,11 +35,11 @@ Changes in 1.2.x
   ``savefig.extension``, and sets the default file format used by
   :meth:`matplotlib.figure.Figure.savefig`.
 
-* In :meth:`~matplotlib.pyplot.pie` and :meth:`~matplotlib.Axes.pie`, one can
-  now set the radius of the pie; setting the *radius* to 'None' (the default
-  value), will result in a pie with a radius of 1 as before.
+* In :func:`.pyplot.pie` and :meth:`.axes.Axes.pie`, one can now set the radius
+  of the pie; setting the *radius* to 'None' (the default value), will result
+  in a pie with a radius of 1 as before.
 
-* Use of :func:`~matplotlib.projections.projection_factory` is now deprecated
+* Use of ``matplotlib.projections.projection_factory`` is now deprecated
   in favour of axes class identification using
   :func:`~matplotlib.projections.process_projection_requirements` followed by
   direct axes class invocation (at the time of writing, functions which do this
@@ -137,7 +137,7 @@ Changes in 1.2.x
   and py2.7. It is anticipated that the Qt3 support will be completely
   removed for the next release.
 
-* :class:`~matplotlib.colors.ColorConverter`,
+* ``matplotlib.colors.ColorConverter``,
   :class:`~matplotlib.colors.Colormap` and
   :class:`~matplotlib.colors.Normalize` now subclasses ``object``
 

diff --git a/doc/api/prev_api_changes/api_changes_1.3.x.rst b/doc/api/prev_api_changes/api_changes_1.3.x.rst
@@ -10,7 +10,7 @@ Changes in 1.3.1
 It is rare that we make an API change in a bugfix release, however,
 for 1.3.1 since 1.3.0 the following change was made:
 
-- `text.Text.cached` (used to cache font objects) has been made into a
+- ``text.Text.cached`` (used to cache font objects) has been made into a
   private variable.  Among the obvious encapsulation benefit, this
   removes this confusing-looking member from the documentation.
 
@@ -24,49 +24,52 @@ Code removal
 * The following items that were deprecated in version 1.2 or earlier
   have now been removed completely.
 
-    - The Qt 3.x backends (`qt` and `qtagg`) have been removed in
-      favor of the Qt 4.x backends (`qt4` and `qt4agg`).
+    - The Qt 3.x backends (``qt`` and ``qtagg``) have been removed in
+      favor of the Qt 4.x backends (``qt4`` and ``qt4agg``).
 
     - The FltkAgg and Emf backends have been removed.
 
-    - The `matplotlib.nxutils` module has been removed.  Use the
+    - The ``matplotlib.nxutils`` module has been removed.  Use the
       functionality on `matplotlib.path.Path.contains_point` and
       friends instead.
 
-    - Instead of `axes.Axes.get_frame`, use `axes.Axes.patch`.
+    - Instead of ``axes.Axes.get_frame``, use `.axes.Axes.patch`.
 
-    - The following `kwargs` to the `legend` function have been
-      renamed:
+    - The following keyword arguments to the `~.axes.Axes.legend` function have
+      been renamed:
 
-      - `pad` -> `borderpad`
-      - `labelsep` -> `labelspacing`
-      - `handlelen` -> `handlelength`
-      - `handletextsep` -> `handletextpad`
-      - `axespad` -> `borderaxespad`
+      - *pad* -> *borderpad*
+      - *labelsep* -> *labelspacing*
+      - *handlelen* -> *handlelength*
+      - *handletextsep* -> *handletextpad*
+      - *axespad* -> *borderaxespad*
 
       Related to this, the following rcParams have been removed:
 
-      - `legend.pad`, `legend.labelsep`, `legend.handlelen`,
-        `legend.handletextsep` and `legend.axespad`
+      - ``legend.pad``,
+      - ``legend.labelsep``,
+      - ``legend.handlelen``,
+      - ``legend.handletextsep`` and
+      - ``legend.axespad``
 
-    - For the `hist` function, instead of `width`, use `rwidth`
+    - For the `~.axes.Axes.hist` function, instead of *width*, use *rwidth*
       (relative width).
 
-    - On `patches.Circle`, the `resolution` kwarg has been removed.
+    - On `.patches.Circle`, the *resolution* keyword argument has been removed.
       For a circle made up of line segments, use
-      `patches.CirclePolygon`.
+      `.patches.CirclePolygon`.
 
     - The printing functions in the Wx backend have been removed due
       to the burden of keeping them up-to-date.
 
-    - `mlab.liaupunov` has been removed.
+    - ``mlab.liaupunov`` has been removed.
 
-    - `mlab.save`, `mlab.load`, `pylab.save` and `pylab.load` have
+    - ``mlab.save``, ``mlab.load``, ``pylab.save`` and ``pylab.load`` have
       been removed.  We recommend using `numpy.savetxt` and
       `numpy.loadtxt` instead.
 
-    - `widgets.HorizontalSpanSelector` has been removed.  Use
-      `widgets.SpanSelector` instead.
+    - ``widgets.HorizontalSpanSelector`` has been removed.  Use
+      `.widgets.SpanSelector` instead.
 
 Code deprecation
 ----------------
@@ -76,35 +79,33 @@ Code deprecation
 
 * The top-level functions in `matplotlib.path` that are implemented in
   C++ were never meant to be public.  Instead, users should use the
-  Pythonic wrappers for them in the `path.Path` and
-  `collections.Collection` classes.  Use the following mapping to update
+  Pythonic wrappers for them in the `.path.Path` and
+  `.collections.Collection` classes.  Use the following mapping to update
   your code:
 
-    - `point_in_path` -> `path.Path.contains_point`
-    - `get_path_extents` -> `path.Path.get_extents`
-    - `point_in_path_collection` -> `collection.Collection.contains`
-    - `path_in_path` -> `path.Path.contains_path`
-    - `path_intersects_path` -> `path.Path.intersects_path`
-    - `convert_path_to_polygons` -> `path.Path.to_polygons`
-    - `cleanup_path` -> `path.Path.cleaned`
-    - `points_in_path` -> `path.Path.contains_points`
-    - `clip_path_to_rect` -> `path.Path.clip_to_bbox`
-
-* `matplotlib.colors.normalize` and `matplotlib.colors.no_norm` have
+    - ``point_in_path`` -> `.path.Path.contains_point`
+    - ``get_path_extents`` -> `.path.Path.get_extents`
+    - ``point_in_path_collection`` -> `.collections.Collection.contains`
+    - ``path_in_path`` -> `.path.Path.contains_path`
+    - ``path_intersects_path`` -> `.path.Path.intersects_path`
+    - ``convert_path_to_polygons`` -> `.path.Path.to_polygons`
+    - ``cleanup_path`` -> `.path.Path.cleaned`
+    - ``points_in_path`` -> `.path.Path.contains_points`
+    - ``clip_path_to_rect`` -> `.path.Path.clip_to_bbox`
+
+* ``matplotlib.colors.normalize`` and ``matplotlib.colors.no_norm`` have
   been deprecated in favour of `matplotlib.colors.Normalize` and
   `matplotlib.colors.NoNorm` respectively.
 
-* The `ScalarMappable` class' `set_colorbar` is now
-  deprecated. Instead, the
-  :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should be
-  used.  In previous Matplotlib versions this attribute was an
-  undocumented tuple of ``(colorbar_instance, colorbar_axes)`` but is
-  now just ``colorbar_instance``. To get the colorbar axes it is
-  possible to just use the
-  :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar
+* The `.ScalarMappable` class' ``set_colorbar`` method is now deprecated.
+  Instead, the :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should
+  be used.  In previous Matplotlib versions this attribute was an undocumented
+  tuple of ``(colorbar_instance, colorbar_axes)`` but is now just
+  ``colorbar_instance``.  To get the colorbar axes it is possible to just use
+  the :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar
   instance.
 
-* The `~matplotlib.mpl` module is now deprecated. Those who relied on this
+* The ``matplotlib.mpl`` module is now deprecated.  Those who relied on this
   module should transition to simply using ``import matplotlib as mpl``.
 
 Code changes
@@ -131,9 +132,9 @@ Code changes
   large ``linewidth``. Previously, :class:`~matplotlib.patches.Patch` used
   ``capstyle='projecting'``.
 
-* `Path` objects can now be marked as `readonly` by passing
-  `readonly=True` to its constructor.  The built-in path singletons,
-  obtained through `Path.unit*` class methods return readonly paths.
+* `.Path` objects can now be marked as *readonly* by passing
+  ``readonly=True`` to its constructor.  The built-in path singletons,
+  obtained through ``Path.unit*`` class methods return readonly paths.
   If you have code that modified these, you will need to make a
   deepcopy first, using either::
 
@@ -144,23 +145,23 @@ Code changes
 
     path = Path.unit_circle().deepcopy()
 
-  Deep copying a `Path` always creates an editable (i.e. non-readonly)
-  `Path`.
+  Deep copying a `.Path` always creates an editable (i.e. non-readonly)
+  `.Path`.
 
 * The list at ``Path.NUM_VERTICES`` was replaced by a dictionary mapping
   Path codes to the number of expected vertices at
   :attr:`~matplotlib.path.Path.NUM_VERTICES_FOR_CODE`.
 
-* To support XKCD style plots, the :func:`matplotlib.path.cleanup_path`
+* To support XKCD style plots, the ``matplotlib.path.cleanup_path``
   method's signature was updated to require a sketch argument. Users of
-  :func:`matplotlib.path.cleanup_path` are encouraged to use the new
+  ``matplotlib.path.cleanup_path`` are encouraged to use the new
   :meth:`~matplotlib.path.Path.cleaned` Path method.
 
 * Data limits on a plot now start from a state of having "null"
   limits, rather than limits in the range (0, 1).  This has an effect
   on artists that only control limits in one direction, such as
-  `axvline` and `axhline`, since their limits will not longer also
-  include the range (0, 1).  This fixes some problems where the
+  `.axes.Axes.axvline` and `.axes.Axes.axhline`, since their limits will no
+  longer also include the range (0, 1).  This fixes some problems where the
   computed limits would be dependent on the order in which artists
   were added to the axes.
 
@@ -174,7 +175,7 @@ Code changes
   width``.
 
 * It is now possible to provide ``number of levels + 1`` colors in the case of
-  `extend='both'` for contourf (or just ``number of levels`` colors for an
+  ``extend='both'`` for contourf (or just ``number of levels`` colors for an
   extend value ``min`` or ``max``) such that the resulting colormap's
   ``set_under`` and ``set_over`` are defined appropriately. Any other number
   of colors will continue to behave as before (if more colors are provided
@@ -195,18 +196,18 @@ Code changes
   raises :class:`NotImplementedError` instead of :class:`OSError` if the
   :command:`ps` command cannot be run.
 
-* The :func:`matplotlib.cbook.check_output` function has been moved to
-  :func:`matplotlib.compat.subprocess`.
+* The ``matplotlib.cbook.check_output`` function has been moved to
+  ``matplotlib.compat.subprocess``.
 
 Configuration and rcParams
 --------------------------
 
-* On Linux, the user-specific `matplotlibrc` configuration file is now
-  located in `~/.config/matplotlib/matplotlibrc` to conform to the
+* On Linux, the user-specific :file:`matplotlibrc` configuration file is now
+  located in :file:`~/.config/matplotlib/matplotlibrc` to conform to the
   `XDG Base Directory Specification
   <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
 
-* The `font.*` rcParams now affect only text objects created after the
+* The ``font.*`` rcParams now affect only text objects created after the
   rcParam has been set, and will not retroactively affect already
   existing text objects.  This brings their behavior in line with most
   other rcParams.