Add transformations/paths information to developer docs.

mdboom · mdboom · commit 6cae124efccd · 2008-06-05T13:45:27.000Z
svn path=/trunk/matplotlib/; revision=5394
diff --git a/doc/conf.py b/doc/conf.py
@@ -159,3 +159,7 @@
 latex_use_modindex = True
 
 latex_use_parts = True
+
+# Show both class-level docstring and __init__ docstring in class
+# documentation
+autoclass_content = 'both'
diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -11,4 +11,6 @@
 
    coding_guide.rst
    documenting_mpl.rst
+   transformations.rst
    add_new_projection.rst
+
diff --git a/doc/devel/transformations.rst b/doc/devel/transformations.rst
@@ -0,0 +1,21 @@
+==============================
+ Working with transformations
+==============================
+
+:mod:`matplotlib.transforms`
+=============================
+
+.. automodule:: matplotlib.transforms
+   :members: TransformNode, BboxBase, Bbox, TransformedBbox, Transform,
+       TransformWrapper, AffineBase, Affine2DBase, Affine2D, IdentityTransform,
+       BlendedGenericTransform, BlendedAffine2D, blended_transform_factory,
+       CompositeGenericTransform, CompositeAffine2D,
+       composite_transform_factory, BboxTransform, BboxTransformTo,
+       BboxTransformFrom, ScaledTranslation, TransformedPath, nonsingular,
+       interval_contains, interval_contains_open
+
+:mod:`matplotlib.path`
+=============================
+
+.. automodule:: matplotlib.path
+   :members: Path, get_path_collection_extents
diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -1,7 +1,5 @@
 """
 Contains a class for managing paths (polylines).
-
-October 2007 Michael Droettboom
 """
 
 import math
@@ -21,42 +19,42 @@ class Path(object):
     closed, line and curve segments.
 
     The underlying storage is made up of two parallel numpy arrays:
-      vertices: an Nx2 float array of vertices
-      codes: an N-length uint8 array of vertex types
+      - vertices: an Nx2 float array of vertices
+      - codes: an N-length uint8 array of vertex types
 
     These two arrays always have the same length in the first
-    dimension.  Therefore, to represent a cubic curve, you must
+    dimension.  For example, to represent a cubic curve, you must
     provide three vertices as well as three codes "CURVE3".
 
     The code types are:
 
-       STOP   :  1 vertex (ignored)
-          A marker for the end of the entire path (currently not
-          required and ignored)
+       - ``STOP``   :  1 vertex (ignored)
+           A marker for the end of the entire path (currently not
+           required and ignored)
 
-       MOVETO :  1 vertex
-          Pick up the pen and move to the given vertex.
+       - ``MOVETO`` :  1 vertex
+            Pick up the pen and move to the given vertex.
 
-       LINETO :  1 vertex
-          Draw a line from the current position to the given vertex.
+       - ``LINETO`` :  1 vertex
+            Draw a line from the current position to the given vertex.
 
-       CURVE3 :  1 control point, 1 endpoint
+       - ``CURVE3`` :  1 control point, 1 endpoint
           Draw a quadratic Bezier curve from the current position,
           with the given control point, to the given end point.
 
-       CURVE4 :  2 control points, 1 endpoint
+       - ``CURVE4`` :  2 control points, 1 endpoint
           Draw a cubic Bezier curve from the current position, with
           the given control points, to the given end point.
 
-       CLOSEPOLY : 1 vertex (ignored)
+       - ``CLOSEPOLY`` : 1 vertex (ignored)
           Draw a line segment to the start point of the current
           polyline.
 
     Users of Path objects should not access the vertices and codes
-    arrays directly.  Instead, they should use iter_segments to get
-    the vertex/code pairs.  This is important since many Paths do not
-    store a codes array at all, but have a default one provided for
-    them by iter_segments.
+    arrays directly.  Instead, they should use :meth:`iter_segments`
+    to get the vertex/code pairs.  This is important since many Paths,
+    as an optimization, do not store a codes array at all, but have a
+    default one provided for them by :meth:`iter_segments`.
     """
 
     # Path codes
@@ -81,9 +79,6 @@ def __init__(self, vertices, codes=None):
         codes is an N-length numpy array or Python sequence of type
         Path.code_type.
 
-        See the docstring of Path for a description of the various
-        codes.
-
         These two arrays must have the same length in the first
         dimension.
 
@@ -133,8 +128,8 @@ def __init__(self, vertices, codes=None):
     #@staticmethod
     def make_compound_path(*args):
         """
-        Make a compound path from a list of Path objects.  Only
-        polygons (not curves) are supported.
+        (staticmethod) Make a compound path from a list of Path
+        objects.  Only polygons (not curves) are supported.
         """
         for p in args:
             assert p.codes is None
@@ -162,7 +157,10 @@ def __len__(self):
 
     def iter_segments(self):
         """
-        Iterates over all of the curve segments in the path.
+        Iterates over all of the curve segments in the path.  Each
+        iteration returns a 2-tuple ``(vertices, code)``, where
+        vertices is a sequence of 1 - 3 coordinate pairs, and code is
+        one of the ``Path`` codes.
         """
         vertices = self.vertices
         if not len(vertices):
@@ -213,9 +211,9 @@ def transformed(self, transform):
         """
         Return a transformed copy of the path.
 
-        See transforms.TransformedPath for a path that will cache the
-        transformed result and automatically update when the transform
-        changes.
+        See :class:`matplotlib.transforms.TransformedPath` for a path
+        that will cache the transformed result and automatically
+        update when the transform changes.
         """
         return Path(transform.transform(self.vertices), self.codes)
 
@@ -233,6 +231,9 @@ def contains_point(self, point, transform=None):
     def contains_path(self, path, transform=None):
         """
         Returns True if this path completely contains the given path.
+
+        If transform is not None, the path will be transformed before
+        performing the test.
         """
         if transform is not None:
             transform = transform.frozen()
@@ -259,7 +260,8 @@ def intersects_path(self, other):
 
     def intersects_bbox(self, bbox):
         """
-        Returns True if this path intersects a given Bbox.
+        Returns True if this path intersects a given
+        :class:`~matplotlib.transforms.Bbox`.
         """
         from transforms import BboxTransformTo
         rectangle = self.unit_rectangle().transformed(
@@ -285,7 +287,9 @@ def to_polygons(self, transform=None, width=0, height=0):
         """
         Convert this path to a list of polygons.  Each polygon is an
         Nx2 array of vertices.  In other words, each polygon has no
-        "move to" instructions or curves.
+        ``MOVETO`` instructions or curves.  This is useful for
+        displaying in backends that do not support compound paths or
+        Bezier curves, such as GDK.
         """
         if transform is not None:
             transform = transform.frozen()
@@ -302,7 +306,8 @@ def to_polygons(self, transform=None, width=0, height=0):
     #@classmethod
     def unit_rectangle(cls):
         """
-        Returns a Path of the unit rectangle from (0, 0) to (1, 1).
+        (staticmethod) Returns a :class:`Path` of the unit rectangle
+        from (0, 0) to (1, 1).
         """
         if cls._unit_rectangle is None:
             cls._unit_rectangle = \
@@ -314,8 +319,9 @@ def unit_rectangle(cls):
     #@classmethod
     def unit_regular_polygon(cls, numVertices):
         """
-        Returns a Path for a unit regular polygon with the given
-        numVertices and radius of 1.0, centered at (0, 0).
+        (staticmethod) Returns a :class:`Path` for a unit regular
+        polygon with the given numVertices and radius of 1.0, centered
+        at (0, 0).
         """
         if numVertices <= 16:
             path = cls._unit_regular_polygons.get(numVertices)
@@ -337,8 +343,9 @@ def unit_regular_polygon(cls, numVertices):
     #@classmethod
     def unit_regular_star(cls, numVertices, innerCircle=0.5):
         """
-        Returns a Path for a unit regular star with the given
-        numVertices and radius of 1.0, centered at (0, 0).
+        (staticmethod) Returns a :class:`Path` for a unit regular star
+        with the given numVertices and radius of 1.0, centered at (0,
+        0).
         """
         if numVertices <= 16:
             path = cls._unit_regular_stars.get((numVertices, innerCircle))
@@ -361,8 +368,9 @@ def unit_regular_star(cls, numVertices, innerCircle=0.5):
     #@classmethod
     def unit_regular_asterisk(cls, numVertices):
         """
-        Returns a Path for a unit regular asterisk with the given
-        numVertices and radius of 1.0, centered at (0, 0).
+        (staticmethod) Returns a :class:`Path` for a unit regular
+        asterisk with the given numVertices and radius of 1.0,
+        centered at (0, 0).
         """
         return cls.unit_regular_star(numVertices, 0.0)
     unit_regular_asterisk = classmethod(unit_regular_asterisk)
@@ -371,14 +379,13 @@ def unit_regular_asterisk(cls, numVertices):
     #@classmethod
     def unit_circle(cls):
         """
-        Returns a Path of the unit circle.  The circle is approximated
-        using cubic Bezier curves.  This uses 8 splines around the
-        circle using the approach presented here:
+        (staticmethod) Returns a :class:`Path` of the unit circle.
+        The circle is approximated using cubic Bezier curves.  This
+        uses 8 splines around the circle using the approach presented
+        here:
 
-        Lancaster, Don.  Approximating a Circle or an Ellipse Using Four
-        Bezier Cubic Splines.
-
-        http://www.tinaja.com/glib/ellipse4.pdf
+          Lancaster, Don.  `Approximating a Circle or an Ellipse Using Four
+          Bezier Cubic Splines <http://www.tinaja.com/glib/ellipse4.pdf>`_.
         """
         if cls._unit_circle is None:
             MAGIC = 0.2652031
@@ -434,18 +441,17 @@ def unit_circle(cls):
     #@classmethod
     def arc(cls, theta1, theta2, n=None, is_wedge=False):
         """
-        Returns an arc on the unit circle from angle theta1 to angle
-        theta2 (in degrees).
+        (staticmethod) Returns an arc on the unit circle from angle
+        theta1 to angle theta2 (in degrees).
 
         If n is provided, it is the number of spline segments to make.
-        If n is not provided, the number of spline segments is determined
-        based on the delta between theta1 and theta2.
-        """
-        # From Masionobe, L.  2003.  "Drawing an elliptical arc using
-        # polylines, quadratic or cubic Bezier curves".
-        #
-        # http://www.spaceroots.org/documents/ellipse/index.html
+        If n is not provided, the number of spline segments is
+        determined based on the delta between theta1 and theta2.
 
+           Masionobe, L.  2003.  `Drawing an elliptical arc using
+           polylines, quadratic or cubic Bezier curves
+           <http://www.spaceroots.org/documents/ellipse/index.html>`_.
+        """
         # degrees to radians
         theta1 *= np.pi / 180.0
         theta2 *= np.pi / 180.0
@@ -514,14 +520,18 @@ def arc(cls, theta1, theta2, n=None, is_wedge=False):
     #@classmethod
     def wedge(cls, theta1, theta2, n=None):
         """
-        Returns a wedge of the unit circle from angle theta1 to angle
-        theta2 (in degrees).
+        (staticmethod) Returns a wedge of the unit circle from angle
+        theta1 to angle theta2 (in degrees).
         """
         return cls.arc(theta1, theta2, n, True)
     wedge = classmethod(wedge)
 
 _get_path_collection_extents = get_path_collection_extents
 def get_path_collection_extents(*args):
+    """
+    Given a sequence of :class:`Path` objects, returns the bounding
+    box that encapsulates all of them.
+    """
     from transforms import Bbox
     if len(args[1]) == 0:
         raise ValueError("No paths provided")
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
