Merge pull request #20319 from QuLogic/doc-api-pages

timhoffm · web-flow · commit 0520d99e9bdd · 2021-05-31T21:12:43.000+02:00
DOC: Tweaks to module API pages
diff --git a/doc/api/animation_api.rst b/doc/api/animation_api.rst
@@ -14,7 +14,7 @@
 Animation
 =========
 
-The easiest way to make a live animation in matplotlib is to use one of the
+The easiest way to make a live animation in Matplotlib is to use one of the
 `Animation` classes.
 
 .. autosummary::
@@ -29,7 +29,7 @@ In both cases it is critical to keep a reference to the instance
 object.  The animation is advanced by a timer (typically from the host
 GUI framework) which the `Animation` object holds the only reference
 to.  If you do not hold a reference to the `Animation` object, it (and
-hence the timers), will be garbage collected which will stop the
+hence the timers) will be garbage collected which will stop the
 animation.
 
 To save an animation to disk use `Animation.save` or `Animation.to_html5_video`
diff --git a/doc/api/colors_api.rst b/doc/api/colors_api.rst
@@ -2,8 +2,11 @@
 ``matplotlib.colors``
 *********************
 
-The Color :ref:`tutorials <tutorials-colors>` and :ref:`examples
-<color_examples>` demonstrate how to set colors and colormaps.
+.. note::
+
+   The Color :ref:`tutorials <tutorials-colors>` and :ref:`examples
+   <color_examples>` demonstrate how to set colors and colormaps. You may want
+   to read those instead.
 
 .. currentmodule:: matplotlib.colors
 
diff --git a/doc/api/dates_api.rst b/doc/api/dates_api.rst
@@ -4,6 +4,7 @@
 
 .. inheritance-diagram:: matplotlib.dates
    :parts: 1
+   :top-classes: matplotlib.ticker.Formatter, matplotlib.ticker.Locator
 
 .. automodule:: matplotlib.dates
    :members:
diff --git a/doc/api/transformations.rst b/doc/api/transformations.rst
@@ -2,7 +2,7 @@
 ``matplotlib.transforms``
 *************************
 
-.. inheritance-diagram:: matplotlib.transforms matplotlib.path
+.. inheritance-diagram:: matplotlib.transforms
    :parts: 1
 
 .. automodule:: matplotlib.transforms
diff --git a/lib/matplotlib/afm.py b/lib/matplotlib/afm.py
@@ -1,7 +1,7 @@
 """
 A python interface to Adobe Font Metrics Files.
 
-Although a number of other python implementations exist, and may be more
+Although a number of other Python implementations exist, and may be more
 complete than this, it was decided not to go with them because they were
 either:
 
diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py
@@ -1,8 +1,10 @@
 """
 Default legend handlers.
 
-It is strongly encouraged to have read the :doc:`legend guide
-</tutorials/intermediate/legend_guide>` before this documentation.
+.. important::
+
+    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
 signature. ::
diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py
@@ -1,9 +1,12 @@
 """
-Numerical python functions written for compatibility with MATLAB
-commands with the same names. Most numerical python functions can be found in
-the `numpy` and `scipy` libraries. What remains here is code for performing
+Numerical Python functions written for compatibility with MATLAB
+commands with the same names. Most numerical Python functions can be found in
+the `NumPy`_ and `SciPy`_ libraries. What remains here is code for performing
 spectral computations.
 
+.. _NumPy: https://numpy.org
+.. _SciPy: https://www.scipy.org
+
 Spectral functions
 ------------------
 
diff --git a/lib/matplotlib/table.py b/lib/matplotlib/table.py
@@ -9,6 +9,11 @@
 """
 Tables drawing.
 
+.. note::
+    The table implementation in Matplotlib is lightly maintained. For a more
+    featureful table implementation, you may wish to try `blume
+    <https://github.com/swfiua/blume>`_.
+
 Use the factory function `~matplotlib.table.table` to create a ready-made
 table from texts. If you need more control, use the `.Table` class and its
 methods.
diff --git a/lib/matplotlib/texmanager.py b/lib/matplotlib/texmanager.py
@@ -17,7 +17,7 @@
 in ~/.matplotlib/tex.cache for reuse between sessions.
 
 `TexManager.get_rgba` can also be used to directly obtain raster output as RGBA
-numpy arrays.
+NumPy arrays.
 """
 
 import functools
diff --git a/lib/matplotlib/tight_layout.py b/lib/matplotlib/tight_layout.py
@@ -3,10 +3,10 @@
 nicely fit in the figure. In doing so, only axis labels, tick labels, axes
 titles and offsetboxes that are anchored to axes are currently considered.
 
-Internally, this module assumes that the margins (left_margin, etc.) which are
-differences between ax.get_tightbbox and ax.bbox are independent of axes
-position. This may fail if Axes.adjustable is datalim. Also, This will fail
-for some cases (for example, left or right margin is affected by xlabel).
+Internally, this module assumes that the margins (left margin, etc.) which are
+differences between ``Axes.get_tightbbox`` and ``Axes.bbox`` are independent of
+Axes position. This may fail if ``Axes.adjustable`` is ``datalim`` as well as
+such cases as when left or right margin are affected by xlabel.
 """
 
 import numpy as np
diff --git a/lib/matplotlib/units.py b/lib/matplotlib/units.py
@@ -5,8 +5,8 @@
 units and units conversion.  Use cases include converters for custom
 objects, e.g., a list of datetime objects, as well as for objects that
 are unit aware.  We don't assume any particular units implementation;
-rather a units implementation must provide the register with the Registry
-converter dictionary and a `ConversionInterface`.  For example,
+rather a units implementation must register with the Registry converter
+dictionary and provide a `ConversionInterface`.  For example,
 here is a complete implementation which supports plotting with native
 datetime objects::
 
