Merge pull request matplotlib#19926 from anntzer/spd

Move custom scales/custom projections docs to module docstrings.

Author: QuLogic

doc/api/prev_api_changes/api_changes_1.2.x.rst

@@ -66,7 +66,7 @@ Changes in 1.2.x
 
   This change means that third party objects can expose themselves as
   Matplotlib axes by providing a ``_as_mpl_axes`` method. See
-  :ref:`adding-new-scales` for more detail.
+  :mod:`matplotlib.projections` for more detail.
 
 * A new keyword *extendfrac* in :meth:`~matplotlib.pyplot.colorbar` and
   :class:`~matplotlib.colorbar.ColorbarBase` allows one to control the size of

doc/devel/add_new_projection.rst

@@ -36,7 +36,6 @@ process or how to fix something feel free to ask on `gitter
    development_setup.rst
    testing.rst
    documenting_mpl.rst
-   add_new_projection.rst
    gitwash/index.rst
    coding_guide.rst
    release_guide.rst

doc/devel/index.rst

@@ -1,3 +1,57 @@
+"""
+Non-separable transforms that map from data space to screen space.
+
+Projections are defined as `~.axes.Axes` subclasses.  They include the
+following elements:
+
+- A transformation from data coordinates into display coordinates.
+
+- An inverse of that transformation.  This is used, for example, to convert
+  mouse positions from screen space back into data space.
+
+- Transformations for the gridlines, ticks and ticklabels.  Custom projections
+  will often need to place these elements in special locations, and Matplotlib
+  has a facility to help with doing so.
+
+- Setting up default values (overriding `~.axes.Axes.cla`), since the defaults
+  for a rectilinear axes may not be appropriate.
+
+- Defining the shape of the axes, for example, an elliptical axes, that will be
+  used to draw the background of the plot and for clipping any data elements.
+
+- Defining custom locators and formatters for the projection.  For example, in
+  a geographic projection, it may be more convenient to display the grid in
+  degrees, even if the data is in radians.
+
+- Set up interactive panning and zooming.  This is left as an "advanced"
+  feature left to the reader, but there is an example of this for polar plots
+  in `matplotlib.projections.polar`.
+
+- Any additional methods for additional convenience or features.
+
+Once the projection axes is defined, it can be used in one of two ways:
+
+- By defining the class attribute ``name``, the projection axes can be
+  registered with `matplotlib.projections.register_projection` and subsequently
+  simply invoked by name::
+
+      fig.add_subplot(projection="my_proj_name")
+
+- For more complex, parameterisable projections, a generic "projection" object
+  may be defined which includes the method ``_as_mpl_axes``. ``_as_mpl_axes``
+  should take no arguments and return the projection's axes subclass and a
+  dictionary of additional arguments to pass to the subclass' ``__init__``
+  method.  Subsequently a parameterised projection can be initialised with::
+
+      fig.add_subplot(projection=MyProjection(param1=param1_value))
+
+  where MyProjection is an object which implements a ``_as_mpl_axes`` method.
+
+A full-fledged and heavily annotated example is in
+:doc:`/gallery/misc/custom_projection`.  The polar plot functionality in
+`matplotlib.projections.polar` may also be of interest.
+"""
+
 from .. import axes, docstring
 from .geo import AitoffAxes, HammerAxes, LambertAxes, MollweideAxes
 from .polar import PolarAxes

lib/matplotlib/projections/__init__.py

@@ -1,10 +1,15 @@
 """
 Scales define the distribution of data values on an axis, e.g. a log scaling.
-
-They are attached to an `~.axis.Axis` and hold a `.Transform`, which is
-responsible for the actual data transformation.
+They are defined as subclasses of `ScaleBase`.
 
 See also `.axes.Axes.set_xscale` and the scales examples in the documentation.
+
+See :doc:`/gallery/scales/custom_scale` for a full example of defining a custom
+scale.
+
+Matplotlib also supports non-separable transformations that operate on both
+`~.axis.Axis` at the same time.  They are known as projections, and defined in
+`matplotlib.projections`.
 """
 
 import inspect
@@ -28,16 +33,20 @@ class ScaleBase:
 
     Scales are separable transformations, working on a single dimension.
 
-    Any subclasses will want to override:
-
-    - :attr:`name`
-    - :meth:`get_transform`
-    - :meth:`set_default_locators_and_formatters`
-
-    And optionally:
-
-    - :meth:`limit_range_for_scale`
-
+    Subclasses should override
+
+    :attr:`name`
+        The scale's name.
+    :meth:`get_transform`
+        A method returning a `.Transform`, which converts data coordinates to
+        scaled coordinates.  This transform should be invertible, so that e.g.
+        mouse positions can be converted back to data coordinates.
+    :meth:`set_default_locators_and_formatters`
+        A method that sets default locators and formatters for an `~.axis.Axis`
+        that uses this scale.
+    :meth:`limit_range_for_scale`
+        An optional method that "fixes" the axis range to acceptable values,
+        e.g. restricting log-scaled axes to positive values.
     """
 
     def __init__(self, axis):
@@ -56,8 +65,7 @@ def __init__(self, axis):
 
     def get_transform(self):
         """
-        Return the :class:`~matplotlib.transforms.Transform` object
-        associated with this scale.
+        Return the `.Transform` object associated with this scale.
         """
         raise NotImplementedError()
 

lib/matplotlib/scale.py

@@ -461,5 +461,5 @@ def f(t):
 plt.show()
 
 ###############################################################################
-# It is also possible to add your own scale, see :ref:`adding-new-scales` for
+# It is also possible to add your own scale, see `matplotlib.scale` for
 # details.