Fix docstrings about refactored markers.

mdboom · Jul 15, 2011 · 243d78d · mdboom · Oct 21, 2011 · pelson
1 parent 83da58e
commit 243d78d
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 44 deletions.
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -5652,33 +5652,7 @@ def scatter(self, x, y, s=20, c='b', marker='o', cmap=None, norm=None,
           *marker*:
             can be one of:
 
-            # TODO: Use documentation in MarkerStyle
-            
-            The marker can also be a tuple (*numsides*, *style*,
-            *angle*), which will create a custom, regular symbol.
-
-              *numsides*:
-                the number of sides
-
-              *style*:
-                the style of the regular symbol:
-
-                =====   =============================================
-                Value   Description
-                =====   =============================================
-                0       a regular polygon
-                1       a star-like symbol
-                2       an asterisk
-                3       a circle (*numsides* and *angle* is ignored)
-                =====   =============================================
-
-              *angle*:
-                the angle of rotation of the symbol
-
-            Finally, *marker* can be (*verts*, 0): *verts* is a
-            sequence of (*x*, *y*) vertices for a custom scatter
-            symbol.  Alternatively, use the kwarg combination
-            *marker* = *None*, *verts* = *verts*.
+            %(MarkerTable)s
 
         Any or all of *x*, *y*, *s*, and *c* may be masked arrays, in
         which case all masks will be combined and only unmasked points

diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -736,19 +736,20 @@ def set_linestyle(self, linestyle):
             linestyle = 'None'
         self._linestyle = linestyle
 
+    @docstring.dedent_interpd
     def set_marker(self, marker):
         """
         Set the line marker
 
-        %s
+        %(MarkerTable)s
 
-        %s
-        """ % (MarkerStyle.style_table, MarkerStyle.accepts)
+        %(MarkerAccepts)s
+        """
         try:
             self._marker.set_marker(marker)
         except ValueError as e:
             verbose.report(str(e))
-
+        
     def set_markeredgecolor(self, ec):
         """
         Set the marker edge color

diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py
@@ -4,9 +4,12 @@
 `~matplotlib.axes.Axes.scatter`.
 """
 
+import textwrap
+
 import numpy as np
 
 from cbook import is_math_text, is_string_like, is_numlike, iterable
+import docstring
 from matplotlib import rcParams
 from path import Path
 from transforms import IdentityTransform, Affine2D
@@ -17,20 +20,43 @@
 
 class MarkerStyle:
     style_table = """
-======================== =====================================================
-marker                   description
-======================== =====================================================
+============================== ===============================================
+marker                         description
+============================== ===============================================
 %s
-``'$...$'``              render the string using mathtext
-(numsides, style, angle) see below
-verts                    where verts is a list of (x, y) pairs in range (0, 1)
-======================== =====================================================
-
-TODO: Describe tuple form
+``'$...$'``                    render the string using mathtext
+*verts*                        a list of (x, y) pairs in range (0, 1)
+(*numsides*, *style*, *angle*) see below
+============================== ===============================================
+
+The marker can also be a tuple (*numsides*, *style*, *angle*), which
+will create a custom, regular symbol.
+
+    *numsides*:
+      the number of sides
+
+    *style*:
+      the style of the regular symbol:
+
+      =====   =============================================
+      Value   Description
+      =====   =============================================
+      0       a regular polygon
+      1       a star-like symbol
+      2       an asterisk
+      3       a circle (*numsides* and *angle* is ignored)
+      =====   =============================================
+
+    *angle*:
+      the angle of rotation of the symbol
+
+For backward compatibility, the form (*verts*, 0) is also accepted,
+but it is equivalent to just *verts* for giving a raw set of vertices
+that define the shape.
 """ 
 
     # TODO: Automatically generate this
-    accepts = """ACCEPTS: [ %s | ``'$...$'`` | tuple ]"""
+    accepts = """ACCEPTS: [ %s | ``'$...$'`` | *tuple* | *Nx2 array* ]"""
 
     markers =  {
         '.'        : 'point',
@@ -603,11 +629,14 @@ def _set_x(self):
         self._path = self._x_path
 
 _styles = [(repr(x), y) for x, y in MarkerStyle.markers.items()]
-_styles.sort()
+_styles.sort(lambda x, y: cmp(x[1], y[1]))
 MarkerStyle.style_table = (
     MarkerStyle.style_table %
-    '\n'.join(['``%7s`` %33s' % (x, y) for (x, y) in _styles]))
+    '\n'.join(['%-30s %-33s' % ('``%s``' % x, y) for (x, y) in _styles]))
 
-MarkerStyle.accepts = (
+MarkerStyle.accepts = textwrap.fill(
     MarkerStyle.accepts %
     ' | '.join(['``%s``' % x for (x, y) in _styles]))
+
+docstring.interpd.update(MarkerTable=MarkerStyle.style_table)
+docstring.interpd.update(MarkerAccepts=MarkerStyle.accepts)