add support for docstring.hardcopy to format the docstrings less verbosesly for interactive use

jdh2358 · jdh2358 · commit b44e8f20b38c · 2008-12-08T23:28:55.000Z
svn path=/trunk/matplotlib/; revision=6526
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,13 @@
+2008-12-08 Some of the changes Michael made to improve the output of
+           the property tables in the rest docs broke of made
+           difficult to use some of the interactive doc helpers, eg
+           setp and getp.  Having all the rest markup in the ipython
+           shell also confused the docstrings.  I added a new rc param
+           docstring.harcopy, to format the docstrings differently for
+           hardcopy and other use.  Ther ArtistInspector could use a
+           little refactoring now since there is duplication of effort
+           between the rest out put and the non-rest output - JDH
+
 2008-12-08 Updated spectral methods (psd, csd, etc.) to scale one-sided
            densities by a factor of 2 and, optionally, scale all densities
            by the sampling frequency.  This gives better MatLab
diff --git a/doc/matplotlibrc b/doc/matplotlibrc
@@ -294,6 +294,9 @@ savefig.dpi       : 80      # figure dots per inch
 #svg.image_noscale : False     # suppress scaling of raster data embedded in SVG
 #svg.embed_chars : True       # embed character outlines in the SVG file
 
+# docstring params
+docstring.hardcopy = True  # set this when you want to generate hardcopy docstring
+
 # Set the verbose flags.  This controls how much information
 # matplotlib gives you at runtime and where it goes.  The verbosity
 # levels are: silent, helpful, debug, debug-annoying.  Any level is
@@ -311,5 +314,6 @@ savefig.dpi       : 80      # figure dots per inch
 #
 # You can access the verbose instance in your code
 #   from matplotlib import verbose.
+
 #verbose.level  : silent      # one of silent, helpful, debug, debug-annoying
 #verbose.fileo  : sys.stdout  # a log filename, sys.stdout or sys.stderr
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1,5 +1,6 @@
 from __future__ import division
 import re, warnings
+import matplotlib
 import matplotlib.cbook as cbook
 from transforms import Bbox, IdentityTransform, TransformedBbox, TransformedPath
 from path import Path
@@ -640,9 +641,12 @@ def __init__(self, o):
         type) and it is your responsibility to make sure this is so.
         """
         if cbook.iterable(o) and len(o): o = o[0]
+
+        self.oorig = o
         if not isinstance(o, type):
             o = type(o)
         self.o = o
+
         self.aliasd = self.get_aliases()
 
     def get_aliases(self):
@@ -735,7 +739,7 @@ def is_alias(self, o):
         if ds is None: return False
         return ds.startswith('alias for ')
 
-    def aliased_name(self, s, target):
+    def aliased_name(self, s):
         """
         return 'PROPNAME or alias' if *s* has an alias, else return
         PROPNAME.
@@ -745,12 +749,29 @@ def aliased_name(self, s, target):
         property, which does not, return 'transform'
         """
 
+        if s in self.aliasd:
+            return s + ''.join([' or %s' % x for x in self.aliasd[s].keys()])
+        else:
+            return s
+
+
+    def aliased_name_rest(self, s, target):
+        """
+        return 'PROPNAME or alias' if *s* has an alias, else return
+        PROPNAME formatted for ReST
+
+        E.g. for the line markerfacecolor property, which has an
+        alias, return 'markerfacecolor or mfc' and for the transform
+        property, which does not, return 'transform'
+        """
+
         if s in self.aliasd:
             aliases = ''.join([' or %s' % x for x in self.aliasd[s].keys()])
         else:
             aliases = ''
         return ':meth:`%s <%s>`%s' % (s, target, aliases)
 
+
     def pprint_setters(self, prop=None, leadingspace=2):
         """
         If *prop* is *None*, return a list of strings of all settable properies
@@ -772,8 +793,36 @@ def pprint_setters(self, prop=None, leadingspace=2):
         attrs.sort()
         lines = []
 
+        for prop, path in attrs:
+            accepts = self.get_valid_values(prop)
+            name = self.aliased_name(prop)
+
+            lines.append('%s%s: %s' %(pad, name, accepts))
+        return lines
+
+    def pprint_setters_rest(self, prop=None, leadingspace=2):
+        """
+        If *prop* is *None*, return a list of strings of all settable properies
+        and their valid values.  Format the output for ReST
+
+        If *prop* is not *None*, it is a valid property name and that
+        property will be returned as a string of property : valid
+        values.
+        """
+        if leadingspace:
+            pad = ' '*leadingspace
+        else:
+            pad  = ''
+        if prop is not None:
+            accepts = self.get_valid_values(prop)
+            return '%s%s: %s' %(pad, prop, accepts)
+
+        attrs = self._get_setters_and_targets()
+        attrs.sort()
+        lines = []
+
         ########
-        names = [self.aliased_name(prop, target) for prop, target in attrs]
+        names = [self.aliased_name_rest(prop, target) for prop, target in attrs]
         accepts = [self.get_valid_values(prop) for prop, target in attrs]
 
         col0_len = max([len(n) for n in names])
@@ -796,7 +845,7 @@ def pprint_setters(self, prop=None, leadingspace=2):
 
         for prop, path in attrs:
             accepts = self.get_valid_values(prop)
-            name = self.aliased_name(prop, path)
+            name = self.aliased_name_rest(prop, path)
 
             lines.append('%s%s: %s' %(pad, name, accepts))
         return lines
@@ -805,20 +854,27 @@ def pprint_getters(self):
         """
         Return the getters and actual values as list of strings.
         """
-        getters = [name for name in dir(self.o)
+
+        o = self.oorig
+        getters = [name for name in dir(o)
                    if name.startswith('get_')
-                   and callable(getattr(self.o, name))]
+                   and callable(getattr(o, name))]
+        #print getters
         getters.sort()
         lines = []
         for name in getters:
-            func = getattr(self.o, name)
+            func = getattr(o, name)
             if self.is_alias(func): continue
+
             try: val = func()
             except: continue
             if getattr(val, 'shape', ()) != () and len(val)>6:
                 s = str(val[:6]) + '...'
             else:
                 s = str(val)
+            s = s.replace('\n', ' ')
+            if len(s)>50:
+                s = s[:50] + '...'
             name = self.aliased_name(name[4:])
             lines.append('    %s = %s' %(name, s))
         return lines
@@ -898,16 +954,16 @@ def getp(o, property=None):
     insp = ArtistInspector(o)
 
     if property is None:
-        print '\n'.join(insp.pprint_getters())
+        ret = insp.pprint_getters()
+        print '\n'.join(ret)
         return
 
     func = getattr(o, 'get_' + property)
-    return func()
 
-def get(o, *args, **kwargs):
-    return getp(o, *args, **kwargs)
-get.__doc__ = getp.__doc__
+    return func()
 
+# alias
+get = getp
 
 def setp(h, *args, **kwargs):
     """
@@ -984,7 +1040,11 @@ def setp(h, *args, **kwargs):
     return [x for x in cbook.flatten(ret)]
 
 def kwdoc(a):
-    return '\n'.join(ArtistInspector(a).pprint_setters(leadingspace=2))
+    hardcopy = matplotlib.rcParams['docstring.hardcopy']
+    if hardcopy:
+        return '\n'.join(ArtistInspector(a).pprint_setters_rest(leadingspace=2))
+    else:
+        return '\n'.join(ArtistInspector(a).pprint_setters(leadingspace=2))
 
 kwdocd = dict()
 kwdocd['Artist'] = kwdoc(Artist)
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -511,6 +511,8 @@ def __call__(self, s):
     'svg.image_inline'  : [True, validate_bool],    # write raster image data directly into the svg file
     'svg.image_noscale' : [False, validate_bool],  # suppress scaling of raster data embedded in SVG
     'svg.embed_char_paths' : [True, validate_bool],  # True to save all characters as paths in the SVG
+
+    'docstring.hardcopy' : [False, validate_bool],  # set this when you want to generate hardcopy docstring
     'plugins.directory' : ['.matplotlib_plugins', str], # where plugin directory is locate
 
     'path.simplify' : [False, validate_bool],
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -323,6 +323,9 @@ numerix      : %(numerix)s  # numpy, Numeric or numarray
 #svg.image_noscale : False     # suppress scaling of raster data embedded in SVG
 #svg.embed_char_paths : True       # embed character outlines in the SVG file
 
+# docstring params
+#docstring.hardcopy = False  # set this when you want to generate hardcopy docstring
+
 # Set the verbose flags.  This controls how much information
 # matplotlib gives you at runtime and where it goes.  The verbosity
 # levels are: silent, helpful, debug, debug-annoying.  Any level is
