Package mvpa :: Package base :: Module dochelpers
[hide private]
[frames] | no frames]

Source Code for Module mvpa.base.dochelpers

  1  #emacs: -*- mode: python-mode; py-indent-offset: 4; indent-tabs-mode: nil -*- 
  2  #ex: set sts=4 ts=4 sw=4 et: 
  3  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ## 
  4  # 
  5  #   See COPYING file distributed along with the PyMVPA package for the 
  6  #   copyright and license terms. 
  7  # 
  8  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ## 
  9  """""" 
 10   
 11  __docformat__ = 'restructuredtext' 
 12   
 13   
14 -def rstUnderline(text, markup):
15 """Add and underline RsT string matching the length of the given string. 16 """ 17 return text + '\n' + markup * len(text)
18 19
20 -def handleDocString(text):
21 """Take care of empty and non existing doc strings.""" 22 if text == None or not len(text): 23 return 'No documentation found. Sorry!' 24 else: 25 # TODO: remove common empty prefix, so we don't offset 26 # documentation too much 27 # to see starts/ends of the lines use 28 # return '\n'.join(['>%s<' % x for x in text.split('\n')]) 29 # function posixpath.commonprefix might be used to detect 30 # common prefix, or just textwrap.dedent 31 return text
32 33
34 -def enhancedDocString(name, lcl, *args):
35 """Generate enhanced doc strings.""" 36 rst_lvlmarkup = ["=", "-", "_"] 37 38 docs = [] 39 docs += [ handleDocString(lcl['__doc__']), 40 rstUnderline('Constructor information for `%s` class' % name, 41 rst_lvlmarkup[2]), 42 handleDocString(lcl['__init__'].__doc__) ] 43 44 if len(args): 45 docs.append(rstUnderline('\nDocumentation for base classes of `%s`' \ 46 % name, rst_lvlmarkup[0])) 47 for i in args: 48 docs += [ rstUnderline('Documentation for class `%s`' % i.__name__, 49 rst_lvlmarkup[1]), 50 handleDocString(i.__doc__) ] 51 52 return '\n\n'.join(docs)
53 54
55 -def enhancedClassDocString(cls, *args):
56 """Generate enhanced doc strings but given a class, not just a name. 57 58 It is to be used from a collector, it whenever class is already created 59 """ 60 name = cls.__name__ 61 lcl = cls.__dict__ 62 rst_lvlmarkup = ["=", "-", "_"] 63 64 initdoc = None 65 if lcl.has_key('__init__'): 66 initdoc = lcl['__init__'].__doc__ 67 68 if lcl.has_key('_paramsdoc'): 69 if initdoc is None: 70 initdoc = "Initialize instance of %s" % name 71 72 # collector provided us with documentation for the parameters 73 if not (":Parameters:" in initdoc): 74 initdoc += "\n\n:Parameters:\n" 75 76 77 # where new line is after :Parameters: 78 nl_index = initdoc.index('\n', initdoc.index(':Parameters:')+1) 79 # how many spaces preceed next line 80 initdoc_therest = initdoc[nl_index+1:] 81 nspaces = len(initdoc_therest) - len(initdoc_therest.lstrip()) 82 initdoc = initdoc[:nl_index+1] + '\n'.join( 83 [' '*nspaces + x for x in cls._paramsdoc.split('\n')]) + \ 84 initdoc[nl_index:] 85 86 docs = [] 87 docs += [ handleDocString(lcl['__doc__']), 88 rstUnderline('Constructor information for `%s` class' % name, 89 rst_lvlmarkup[2]), 90 handleDocString(initdoc) ] 91 92 if len(args): 93 docs.append(rstUnderline('\nDocumentation for base classes of `%s`' \ 94 % name, rst_lvlmarkup[0])) 95 for i in args: 96 docs += [ rstUnderline('Documentation for class `%s`' % i.__name__, 97 rst_lvlmarkup[1]), 98 handleDocString(i.__doc__) ] 99 100 return '\n\n'.join(docs)
101