Improved docstrings, mainly annotate, base pylab

svn path=/trunk/matplotlib/; revision=3533

lib/matplotlib/__init__.py

@@ -1,5 +1,5 @@
 """
-This is a matlab(TM) style functional interface the matplotlib.
+This is an object-orient plotting library.
 
 The following matlab(TM) compatible commands are provided by
 
@@ -901,4 +901,4 @@ def __init__(self, modstr):
             basemod = __import__(wholename)
             mod = getattr(basemod, name)
             setattr(self, name, mod)
-            
+

lib/matplotlib/artist.py

@@ -136,27 +136,27 @@ def hitlist(self,event):
         if hasattr(self,'get_children'):
             for a in self.get_children(): L.extend(a.hitlist(event))
         return L
-    
+
     def contains(self,mouseevent):
-        """Test whether the artist contains the mouse event.  
-        
-        Returns the truth value and a dictionary of artist specific details of 
-        selection, such as which points are contained in the pick radius.  See 
+        """Test whether the artist contains the mouse event.
+
+        Returns the truth value and a dictionary of artist specific details of
+        selection, such as which points are contained in the pick radius.  See
         individual artists for details.
         """
         if callable(self._contains): return self._contains(self,mouseevent)
         #raise NotImplementedError,str(self.__class__)+" needs 'contains' method"
         print str(self.__class__)+" needs 'contains' method"
         return False,{}
-    
+
     def set_contains(self,picker):
         """Replace the contains test used by this artist. The new picker should
         be a callable function which determines whether the artist is hit by the
         mouse event:
 
             hit, props = picker(artist, mouseevent)
 
-        If the mouse event is over the artist, return hit=True and props 
+        If the mouse event is over the artist, return hit=True and props
         is a dictionary of properties you want returned with the contains test.
         """
         self._contains = picker
@@ -680,7 +680,7 @@ def setp(h, *args, **kwargs):
     return [x for x in flatten(ret)]
 
 def kwdoc(a):
-    return '\n'.join(ArtistInspector(a).pprint_setters(leadingspace=8))
+    return '\n'.join(ArtistInspector(a).pprint_setters(leadingspace=4))
 
 kwdocd = dict()
 kwdocd['Artist'] = kwdoc(Artist)

lib/matplotlib/axes.py

@@ -9,8 +9,8 @@
 rcParams = matplotlib.rcParams
 
 # import a bunch of matplotlib modules into a single namespace
-mpl = matplotlib.Importer("""artist, agg, axis, cbook, collections, colors, 
-     contour, dates, font_manager, image, legend, lines, mlab, cm, 
+mpl = matplotlib.Importer("""artist, agg, axis, cbook, collections, colors,
+     contour, dates, font_manager, image, legend, lines, mlab, cm,
      patches, quiver, table, text, ticker, transforms""")
 
 def delete_masked_points(*args):
@@ -2136,10 +2136,11 @@ def text(self, x, y, s, fontdict=None,
 
     def annotate(self, *args, **kwargs):
         """
-        annotate(self, s, xy, textloc,
-                 xycoords='data', textcoords='data',
-                 lineprops=None,
-                 markerprops=None
+        annotate(s, xy,
+                 xytext=None,
+                 xycoords='data',
+                 textcoords='data',
+                 arrowprops=None,
                  **props)
 
         %(Annotation)s
@@ -4242,7 +4243,7 @@ def fill(self, *args, **kwargs):
           axes.fill(xs, ys, facecolor='red', alpha=0.5)
 
         See examples/fill_between.py for more examples.
-        
+
         kwargs control the Polygon properties:
         %(Polygon)s
         """

lib/matplotlib/cbook.py

@@ -546,7 +546,7 @@ def dedent(s):
     """
     if not s:      # includes case of s is None
         return ''
-    lines = s.splitlines(True)
+    lines = s.splitlines(False)
     ii = 0
     while lines[ii].strip() == '':
         ii += 1
@@ -555,7 +555,7 @@ def dedent(s):
     for i, line in enumerate(lines):
         nwhite = len(line) - len(line.lstrip())
         lines[i] = line[min(nshift, nwhite):]
-    return ''.join(lines)
+    return '\n'.join(lines)
 
 
 
@@ -906,7 +906,7 @@ def print_path(path):
                 outstream.write(repr(step))
             outstream.write(" ->\n")
         outstream.write("\n")
-    
+
     def recurse(obj, start, all, current_path):
         if show_progress:
             outstream.write("%d\r" % len(all))
@@ -923,7 +923,7 @@ def recurse(obj, start, all, current_path):
             # Don't go back through the original list of objects, or
             # through temporary references to the object, since those
             # are just an artifact of the cycle detector itself.
-            elif referent is objects or isinstance(referent, FrameType): 
+            elif referent is objects or isinstance(referent, FrameType):
                 continue
 
             # We haven't seen this object before, so recurse

lib/matplotlib/pylab.py

@@ -1,9 +1,9 @@
 """
-This is a procedural interface to matplotlib.
+This is a procedural interface to the matplotlib object-oriented
+plotting library.
 
-The following plotting commands are provided; some of these do not
-exist in matlab(TM) but have proven themselves to be useful nonetheless.
-The majority of them, however, have matlab analogs
+The following plotting commands are provided; the majority have
+Matlab(TM) analogs and similar argument.
 
 _Plotting commands
   acorr     - plot the autocorrelation function

lib/matplotlib/text.py

@@ -94,36 +94,36 @@ def get_rotation(rotation):
 # class is build so we define an initial set here for the init
 # function and they will be overridden after object defn
 artist.kwdocd['Text'] =  """\
-            alpha: float
-            animated: [True | False]
-            backgroundcolor: any matplotlib color
-            bbox: rectangle prop dict plus key 'pad' which is a pad in points
-            clip_box: a matplotlib.transform.Bbox instance
-            clip_on: [True | False]
-            color: any matplotlib color
-            family: [ 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
-            figure: a matplotlib.figure.Figure instance
-            fontproperties: a matplotlib.font_manager.FontProperties instance
-            horizontalalignment or ha: [ 'center' | 'right' | 'left' ]
-            label: any string
-            linespacing: float
-            lod: [True | False]
-            multialignment: ['left' | 'right' | 'center' ]
-            name or fontname: string eg, ['Sans' | 'Courier' | 'Helvetica' ...]
-            position: (x,y)
-            rotation: [ angle in degrees 'vertical' | 'horizontal'
-            size or fontsize: [ size in points | relative size eg 'smaller', 'x-large' ]
-            style or fontstyle: [ 'normal' | 'italic' | 'oblique']
-            text: string
-            transform: a matplotlib.transform transformation instance
-            variant: [ 'normal' | 'small-caps' ]
-            verticalalignment or va: [ 'center' | 'top' | 'bottom' ]
-            visible: [True | False]
-            weight or fontweight: [ 'normal' | 'bold' | 'heavy' | 'light' | 'ultrabold' | 'ultralight']
-            x: float
-            y: float
-            zorder: any number
-            """
+    alpha: float
+    animated: [True | False]
+    backgroundcolor: any matplotlib color
+    bbox: rectangle prop dict plus key 'pad' which is a pad in points
+    clip_box: a matplotlib.transform.Bbox instance
+    clip_on: [True | False]
+    color: any matplotlib color
+    family: [ 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
+    figure: a matplotlib.figure.Figure instance
+    fontproperties: a matplotlib.font_manager.FontProperties instance
+    horizontalalignment or ha: [ 'center' | 'right' | 'left' ]
+    label: any string
+    linespacing: float
+    lod: [True | False]
+    multialignment: ['left' | 'right' | 'center' ]
+    name or fontname: string eg, ['Sans' | 'Courier' | 'Helvetica' ...]
+    position: (x,y)
+    rotation: [ angle in degrees 'vertical' | 'horizontal'
+    size or fontsize: [ size in points | relative size eg 'smaller', 'x-large' ]
+    style or fontstyle: [ 'normal' | 'italic' | 'oblique']
+    text: string
+    transform: a matplotlib.transform transformation instance
+    variant: [ 'normal' | 'small-caps' ]
+    verticalalignment or va: [ 'center' | 'top' | 'bottom' ]
+    visible: [True | False]
+    weight or fontweight: [ 'normal' | 'bold' | 'heavy' | 'light' | 'ultrabold' | 'ultralight']
+    x: float
+    y: float
+    zorder: any number
+    """
 
 class Text(Artist):
     """
@@ -149,8 +149,10 @@ def __init__(self,
                  **kwargs
                  ):
         """
-        Create a Text instance at x,y with string text.  Valid kwargs are
-            %(Text)s
+        Create a Text instance at x,y with string text.
+
+        Valid kwargs are
+        %(Text)s
         """
 
         Artist.__init__(self)
@@ -817,6 +819,7 @@ def _get_layout_super(self, renderer, m):
 
         return val
 
+artist.kwdocd['Text'] = artist.kwdoc(Text)
 
 
 class TextWithDash(Text):
@@ -1125,6 +1128,7 @@ def set_figure(self, fig):
         Text.set_figure(self, fig)
         self.dashline.set_figure(fig)
 
+artist.kwdocd['TextWithDash'] = artist.kwdoc(TextWithDash)
 
 class Annotation(Text):
     """
@@ -1134,8 +1138,8 @@ class Annotation(Text):
     def __str__(self):
         return "Annotation(%g,%g,%s)"%(self.xy[0],self.xy[1],self._text)
     def __init__(self, s, xy,
-                 xycoords='data',
                  xytext=None,
+                 xycoords='data',
                  textcoords=None,
                  arrowprops=None,
                  **kwargs):
@@ -1159,7 +1163,7 @@ def __init__(self, s, xy,
             endpoints.  ie, shrink=0.05 is 5%%
           - any key for matplotlib.patches.polygon
 
-        xycoords and textcoords are a string that indicates the
+        xycoords and textcoords are strings that indicate the
         coordinates of xy and xytext.
 
            'figure points'   : points from the lower left corner of the figure
@@ -1184,7 +1188,7 @@ def __init__(self, s, xy,
 
         Additional kwargs are Text properties:
 
-          %(Text)s
+        %(Text)s
 
         """
         if xytext is None:
@@ -1344,6 +1348,4 @@ def draw(self, renderer):
         Text.draw(self, renderer)
 
 
-artist.kwdocd['Text'] = artist.kwdoc(Text)
-artist.kwdocd['TextWithDash'] = artist.kwdoc(TextWithDash)
-artist.kwdocd['Annotation'] = artist.kwdoc(Annotation)
+artist.kwdocd['Annotation'] = Annotation.__init__.__doc__

lib/pylab.py

@@ -1 +1,3 @@
 from matplotlib.pylab import *
+import matplotlib.pylab
+__doc__ = matplotlib.pylab.__doc__