Source Code for Module Ganga.Runtime.gangadoc

  1  ################################################################################ 
  2  # Ganga Project. http://cern.ch/ganga 
  3  # 
  4  # $Id: gangadoc.py,v 1.1 2008-07-17 16:41:00 moscicki Exp $ 
  5  ################################################################################ 
  6   
  7  """Improved support for interactive help based on pydoc. 
  8  Remove hardcoded limits on the help text. 
  9  This module makes changes to the content of the pydoc module. 
 10  """ 
 11   
 12  import pydoc 
 13   
 14  _GPIhelp = '''Ganga Public Interface (GPI) Index 
 15   
 16  %(Classes)s 
 17   
 18  %(Exceptions)s 
 19   
 20  %(Functions)s 
 21   
 22  %(Objects)s 
 23   
 24  ''' 
 25   
 26  _GPIhelp_sections = { 'Classes' : [], 'Exceptions' : [], 'Functions' : [], 'Objects' : [] } 
 27   
 28 -def adddoc(name,object,doc_section,docstring): 
 29      ''' 
 30      Add automatic documentation to gangadoc system. 
 31      "doc_section" specifies how the object should be documented. 
 32      If docstring is specified then use it to document the object. Otherwise use __doc__ (via pydoc utilities). 
 33      ''' 
 34      from Ganga.Utility.logic import implies 
 35      assert(implies(docstring, doc_section=="Objects")) 
 36      #assert(not docstring and not object.__doc__) 
 37       
 38      _GPIhelp_sections[doc_section] += [(name,object,docstring)] 
 39       
 40 -def makedocindex(): 
 41      ''' 
 42      Return a string with GPI Index. 
 43      ''' 
 44   
 45      import pydoc 
 46       
 47      sections = {} 
 48   
 49      from Ganga.Utility.strings import ItemizedTextParagraph 
 50       
 51      for sec,names in zip(_GPIhelp_sections.keys(),_GPIhelp_sections.values()): 
 52          itbuf = ItemizedTextParagraph(sec+':') 
 53          for name,obj,docstring in names: 
 54              # if docstring not provided when exporting the object to GPI then use the docstring generated by pydoc 
 55              if not docstring: 
 56                  docstring = pydoc.splitdoc(pydoc.getdoc(obj))[0] 
 57              itbuf.addLine(name,docstring) 
 58   
 59          sections[sec] = itbuf.getString() 
 60   
 61      return _GPIhelp % sections 
 62           
 63   
 64  ## modifications to pydoc module 
 65   
 66  # a workaround for hardcoded limit of maxlen==70 characters  
 67 -class TextDoc2(pydoc.TextDoc): 
 68 -    def docother(self, object, name=None, mod=None, maxlen=None, doc=None): 
 69          return pydoc.TextDoc.docother(self,object,name=name,mod=mod,doc=doc) 
 70   
 71 -class Helper2(pydoc.Helper): 
 72 -    def __init__(self,*args,**kwds): 
 73          pydoc.Helper.__init__(self,*args,**kwds) 
 74   
 75 -    def intro(self): 
 76           
 77          from Ganga.Runtime import _prog 
 78           
 79          self.output.write("""************************************ 
 80  %s 
 81   
 82  This is an interactive help based on standard pydoc help. 
 83   
 84  Type 'index'  to see GPI help index. 
 85  Type 'python' to see standard python help screen. 
 86  Type 'interactive' to get online interactive help from an expert. 
 87  Type 'quit'   to return to Ganga. 
 88  ************************************ 
 89  """%(_prog.hello_string)) 
 90   
 91 -    def help(self, request): 
 92          if type(request) is type(''): 
 93              if request == 'python': 
 94                  pydoc.Helper.intro(self) 
 95                  return 
 96   
 97              if request == 'index': 
 98                  self.output.write(makedocindex()) 
 99                  return 
100   
101              if request == 'interactive': 
102                  import eliza 
103                  self.output.write(""" 
104  This is an interactive help. At the prompt type your questions in plain english\n\n""") 
105                  eliza.command_interface() 
106                  return 
107   
108              # eval the expression (in the context of Ganga.GPI namespace) 
109              from gangadoceval import evaluate 
110              request = evaluate(request) 
111   
112          return pydoc.Helper.help(self,request) 
113               
114  pydoc.text = TextDoc2() 
115  pydoc.text._repr_instance.maxstring = 255 
116  pydoc.text._repr_instance.maxother = 70 
117   
118  import sys 
119   
120  pydoc.help = Helper2(sys.stdin, sys.stdout) 
121   
122   
123  #bugfix: #18012 overview: No help text avaialable for "jobs" 
124  #with python2.4 should not be needed (?) 
125  #patch the  doc method  from pydoc module  to support  documenting, in 
126  #case of  af an instance,  the structure of  its class instead  of its 
127  #value 
128  # & 
129  #bugfix: #12584  
130  #overview: for some (unknown) reason the IPython code inserts an instance of 
131  #IPython.FakeModule.FakeModule class in sys.modules 
132  #inspect.getmodule(object) method raises in this a TypeError 
133  #workaround: use an improved getmodule(object) method that does supplementary checks 
134  #Notes: 
135  #Running with Python2.2 IPython seems to insert a *stripped* version of FakeModule in sys.module which masks this bug 
136  #This bug persists in IPython/Python 2.4 too 
137   
138   
139  modulesbyfile = {} 
140  import inspect 
141 -def mygetmodule(object): 
142      """Return the module an object was defined in, or None if not found.""" 
143      import os.path 
144      if inspect.ismodule(object): 
145          return object 
146      if hasattr(object, '__module__'): 
147          return sys.modules.get(object.__module__) 
148      try: 
149          file = inspect.getabsfile(object) 
150      except TypeError: 
151          return None 
152      if modulesbyfile.has_key(file): 
153          return sys.modules.get(modulesbyfile[file]) 
154      for module in sys.modules.values(): 
155          if inspect.ismodule(module) and hasattr(module, '__file__'): #check if value is indeed a module 
156              modulesbyfile[os.path.realpath(inspect.getabsfile(module))] = module.__name__ 
157      if modulesbyfile.has_key(file): 
158          return sys.modules.get(modulesbyfile[file]) 
159      main = sys.modules['__main__'] 
160      if not hasattr(object, '__name__'): 
161          return None 
162      if hasattr(main, object.__name__): 
163          mainobject = getattr(main, object.__name__) 
164          if mainobject is object: 
165              return main 
166      builtin = sys.modules['__builtin__'] 
167      if hasattr(builtin, object.__name__): 
168          builtinobject = getattr(builtin, object.__name__) 
169          if builtinobject is object: 
170              return builtin 
171   
172   
173 -def doc2(thing, title='Python Library Documentation: %s', forceload=0): 
174      """Display text documentation, given an object or a path to an object.""" 
175      import types 
176      try: 
177          object, name = pydoc.resolve(thing, forceload) 
178          desc = pydoc.describe(object) 
179          module = mygetmodule(object) 
180          if name and '.' in name: 
181              desc += ' in ' + name[:name.rfind('.')] 
182          elif module and module is not object: 
183              desc += ' in module ' + module.__name__ 
184   
185          if not (inspect.ismodule(object) or 
186                  inspect.isclass(object) or 
187                  inspect.isroutine(object) or 
188                  isinstance(object, property)): 
189              # If the passed object is a piece of data or an instance, 
190              # document its available methods instead of its value. 
191   
192              #if this is a instance of used defined old-style class 
193              if type(object)==types.InstanceType: 
194                  object = object.__class__ 
195              else: 
196                  object = type(object) 
197              desc += ' object' 
198          pydoc.pager(title % desc + '\n\n' + pydoc.text.document(object, name)) 
199      except (ImportError, pydoc.ErrorDuringImport), value: 
200          print value 
201   
202  pydoc.doc = doc2 
203   
204   
205  # 
206  # 
207  # $Log: not supported by cvs2svn $ 
208  # Revision 1.6  2007/07/10 13:08:32  moscicki 
209  # docstring updates (ganga devdays) 
210  # 
211  # Revision 1.5  2006/08/09 08:55:13  adim 
212  # bugfix: #12584 
213  # overview: IPython code inserts an instance of IPython.FakeModule.FakeModule class in sys.modules 
214  # which breaks the help system. 
215  # 
216  # Revision 1.4  2006/07/12 12:40:45  moscicki 
217  # bugfix: #18012 overview: No help text avaialable for "jobs" 
218  # 
219  # Revision 1.3  2006/02/10 14:17:08  moscicki 
220  # fixed bugs: 
221  # #14136 help system doesn't find documentation. 
222  # 
223  # Revision 1.2  2005/08/31 15:06:14  andrew 
224  # add the interactive help system 
225  # 
226  # Revision 1.1  2005/08/24 15:24:11  moscicki 
227  # added docstrings for GPI objects and an interactive ganga help system based on pydoc 
228  # 
229  # 
230  # 
231