diff options
Diffstat (limited to 'sandbox/dkuhlman/Extract/extract_doc.py')
| -rwxr-xr-x | sandbox/dkuhlman/Extract/extract_doc.py | 436 |
1 files changed, 0 insertions, 436 deletions
diff --git a/sandbox/dkuhlman/Extract/extract_doc.py b/sandbox/dkuhlman/Extract/extract_doc.py deleted file mode 100755 index 2ac742de8..000000000 --- a/sandbox/dkuhlman/Extract/extract_doc.py +++ /dev/null @@ -1,436 +0,0 @@ -#!/usr/bin/env python - -import sys -import string -import time -import getopt -import textwrap -import traceback -import inspect -import __builtin__ - -from pydoc import * - - -TARGET_rest = 1 -TARGET_latex = 2 -UseOverTitleAdornment = 0 -TitleAdornmentChars_noover = '=-.,^+~:;_"\'' -TitleAdornmentChars_over = '==--..,,^^++~~' -TitleAdornmentChars = TitleAdornmentChars_noover - - -## class Doc: -## def document(self, thing, name=None, *args): -## """Generate documentation for an object.""" -## args = (thing, name) + args -## # 'try' clause is to attempt to handle the possibility that inspect -## # identifies something in a way that pydoc itself has issues handling; -## # think 'super' and how it is a descriptor (which raises the exception -## # by lacking a __name__ attribute) and an instance. -## ## try: -## if inspect.ismodule(thing): -## result = self.docmodule(*args) -## return result -## if inspect.isclass(thing): -## result = self.docclass(*args) -## return result -## if inspect.isroutine(thing): -## result = self.docroutine(*args) -## return result -## ## except AttributeError: -## ## traceback.print_last() -## ## pass -## result = self.docother(*args) -## return result -## -## def fail(self, thing, name=None, *args): -## """Raise an exception for unimplemented types.""" -## message = "don't know how to document thing%s of type %s" % ( -## name and ' ' + repr(name), type(thing).__name__) -## raise TypeError, message -## -## docmodule = docclass = docroutine = docother = fail - - -class ReSTDoc(Doc): - """Formatter class for reStructuredText documentation.""" - - def __init__(self): - self.lines = [] - self.titleLevel = 0 - - _repr_instance = TextRepr() - repr = _repr_instance.repr - - def push(self, text=''): - """Push one line of output onto the collected output.""" - self.lines.append(text) - - def get_lines(self): - """Get the accumulated lines of output.""" - return self.lines - - def emphasize(self, text): - """Add emphasis to a piece of text.""" - text1 = '*%s*' % text - return text1 - - def formatvalue(self, thing): - """Format an argument default value as text.""" - return '=' + self.repr(thing) - - def escape(self, text): - """Escape special reStructuredText characters.""" - text1 = text.replace('*', '\\*') - return text1 - - def genTitle(self, text): - """Generate a title according to the current title level.""" - adornment = TitleAdornmentChars[self.titleLevel] - # If it's an even numbered title level, then generate - # adornment above the title. - if UseOverTitleAdornment: - if ((self.titleLevel / 2) * 2) == self.titleLevel: - self.push(adornment * len(text)) - self.push(text) - self.push(adornment * len(text)) - self.push() - - def incTitleLevel(self): - self.titleLevel += 1 - - def decTitleLevel(self): - self.titleLevel -= 1 - - def docmodule(self, thing, name=None, mod=None): - """Produce text documentation for a given module object.""" - # Ignore the passed-in name. - name = thing.__name__ - synop, desc = splitdoc(getdoc(thing)) - self.genTitle('SYNOPSIS') - if synop: - line = '%s -- %s' % (name, synop) - line = textwrap.fill(line, 68) - else: - line = name - self.push(line) - self.push() - self.genTitle('DESCRIPTION') - if desc: - self.push(desc) - else: - self.push('No description for this module') - self.push() - classes = [] - for key, value in inspect.getmembers(thing, inspect.isclass): - if (inspect.getmodule(value) or thing) is thing: - if visiblename(key): - classes.append((key, value)) - funcs = [] - for key, value in inspect.getmembers(thing, inspect.isroutine): - if inspect.isbuiltin(value) or inspect.getmodule(value) is thing: - if visiblename(key): - funcs.append((key, value)) - data = [] - for key, value in inspect.getmembers(thing, isdata): - if visiblename(key): - data.append((key, value)) - self.genTitle('CLASSES') - self.incTitleLevel() - if classes: - for key, value in classes: - self.document(value, key, name) - else: - self.push('No classes in this module') - self.push() - self.decTitleLevel() - self.genTitle('FUNCTIONS') - self.incTitleLevel() - if funcs: - for key, value in funcs: - self.document(value, key, name) - else: - self.push('No global functions in this module') - self.push() - self.decTitleLevel() - self.genTitle('DATA') - self.incTitleLevel() - if data: - for key, value in data: - self.document(value, key, name) - else: - self.push('No global data in this module') - self.push() - self.decTitleLevel() - if hasattr(thing, '__version__'): - version = str(thing.__version__) - if version[:11] == '$' + 'Revision: ' and version[-1:] == '$': - version = strip(version[11:-1]) - self.genTitle('VERSION') - self.push(version) - self.push() - if hasattr(thing, '__date__'): - self.genTitle('DATE') - self.push(thing.__date__) - self.push() - if hasattr(thing, '__author__'): - self.genTitle('AUTHOR') - self.push(thing.__author__) - self.push() - if hasattr(thing, '__credits__'): - self.genTitle('CREDITS') - self.push(thing.__credits__) - self.push() - - def genlevel(self, level): - pad = ' ' * level - return pad - - def genbases(self, obj): - level = 0 - self.genbases_aux(obj, level) - - def genbases_aux(self, obj, level): - bases = obj.__bases__ - for base in bases: - pad = self.genlevel(level) - self.push('%s- %s' % (pad, base.__name__)) - self.push() - self.genbases_aux(base, level + 1) - - def docclass(self, thing, name=None, mod=None): - """Produce text documentation for a given class object.""" - realname = thing.__name__ - name = name or realname - self.genTitle('class %s' % name) - self.incTitleLevel() - docstr = getdoc(thing) - self.genTitle('Description') - if docstr: - self.push(docstr) - else: - self.push('No documentation for this class.') - self.push() - self.genTitle('Base Classes') - if thing.__bases__: - self.genbases(thing) - else: - self.push('No superclasses for this class.') - self.push() - attrs = filter(lambda (name, kind, cls, value): visiblename(name), - inspect.classify_class_attrs(thing)) - self.genTitle('Methods') - self.incTitleLevel() - found = 0 - for attr in attrs: - if attr[1] == 'method': - self.document(attr[3], attr[0]) - found = 1 - if not found: - self.push('No methods for this class') - self.decTitleLevel() - self.genTitle('Data') - self.incTitleLevel() - found = 0 - for attr in attrs: - if attr[1] == 'data': - self.document(attr[3], attr[0]) - found = 1 - if not found: - self.push('No data for this class') - self.push() - self.decTitleLevel() - self.decTitleLevel() - - def docroutine(self, thing, name=None, mod=None, cl=None): - """Produce text documentation for a function or method object.""" - realname = thing.__name__ - name = name or realname - note = '' - skipdocs = 0 - if inspect.ismethod(thing): - imclass = thing.im_class - if cl: - if imclass is not cl: - note = 'from ' + classname(imclass, mod) - else: - if thing.im_self: - note = 'method of %s instance' % classname( - thing.im_self.__class__, mod) - else: - note = 'unbound %s method' % classname(imclass,mod) - thing = thing.im_func - if name == realname: - title = self.emphasize(realname) - else: - if (cl and realname in cl.__dict__ and - cl.__dict__[realname] is thing): - skipdocs = 1 - title = '%s = %s' % (self.emphasize(name), realname) - if inspect.isfunction(thing): - args, varargs, varkw, defaults = inspect.getargspec(thing) - argspec = inspect.formatargspec( - args, varargs, varkw, defaults, formatvalue=self.formatvalue) - if realname == '<lambda>': - title = 'lambda' - argspec = argspec[1:-1] # remove parentheses - else: - argspec = '(...)' - argspec = self.escape(argspec) - decl = '%s %s %s' % (title, argspec, note) - if inspect.isfunction(thing): - line = 'function %s' % name - elif inspect.ismethod(thing): - line = 'method %s' % name - else: - line = 'thing %s' % name - self.genTitle(line) - self.incTitleLevel() - self.genTitle('Prototype') - self.push(decl) - self.push() - if not skipdocs: - self.genTitle('Description') - doc = getdoc(thing) - if doc: - doc = doc.rstrip() - self.push(doc) - else: - self.push('No description for this function/method.') - self.push() - self.decTitleLevel() - - def docother(self, thing, name=None, mod=None, maxlen=None, doc=None): - """Produce text documentation for a data object.""" - objRepr = self.repr(thing) - if name: - line = '- %s = %s' % (self.emphasize(name), objRepr) - else: - line = objRepr - self.push(line) - self.push() - -# end class ReSTDoc - - -class PythonLaTeXDoc(Doc): - pass - - -def extract_to_rest(thing, - usePager=None, - title='Python Library Documentation: %s', - forceload=0 - ): - """Display reSturcturedText documentation, given - an object or a path to an object. - Push the resulting text through a pager, if requested, - else print it to stdout. - Add a minimal amount of header and trailer information to - the document. - """ - formatter = ReSTDoc() - try: - thing1, name = resolve(thing, forceload) - except (ImportError, ErrorDuringImport), value: - print value - return - desc = describe(thing1) - module = inspect.getmodule(thing1) - if name and '.' in name: - desc += ' in ' + name[:name.rfind('.')] - elif module and module is not thing1: - desc += ' in module ' + module.__name__ - title1 = title % desc - formatter.genTitle(title1) - formatter.incTitleLevel() - # - # Add and replace header content here. - # - formatter.push('Generated by extract_doc.py on %s.' % time.ctime()) - formatter.push() - formatter.document(thing1, name) - # - # Add and replace trailer content here. - # - doclines = formatter.get_lines() - content = '\n'.join(doclines) - # - # Add and replace post-processing here. - # You might consider sending the output through one of the - # reSTructuredText writers. - # - if usePager: - pager(content) - else: - sys.stdout.write(content) - sys.stdout.write('\n') - - -def extract_to_latex(module_name): - print 'Not implemented yet' - - - - -USAGE_TEXT = """ -Usage: - python extract_doc.py [options] <module_name> -Options: - -h, --help Display this help message. - -r, --rest Extract to decorated reST. - -l, --latex Extract to Python LaTeX (module doc type). Not implemented. - -p, --pager Use a pager; else write to stdout. - -o, --over Use over *and* under title adornment, else only under. -Example: - python extract_doc.py -r mymodule1 - python extract_doc.py -p -o -r mymodule2 -""" - -def usage(): - print USAGE_TEXT - sys.exit(-1) - - -def main(): - global UseOverTitleAdornment, TitleAdornmentChars - args = sys.argv[1:] - try: - opts, args = getopt.getopt(args, 'hrlpdo', - ['help', 'rest', 'latex', 'pager', 'over']) - except: - usage() - target = None - usePager = None - for opt, val in opts: - if opt in ('-h', '--help'): - usage() - elif opt in ('-r', '--rest'): - target = TARGET_rest - elif opt in ('-l', '--latex'): - target = TARGET_latex - elif opt in ('-p', '--pager'): - usePager = 1 - elif opt in ('-o', '--over'): - UseOverTitleAdornment = 1 - TitleAdornmentChars = TitleAdornmentChars_over - if len(args) != 1: - usage() - if target == TARGET_rest: - extract_to_rest(args[0], usePager) - elif target == TARGET_latex: - extract_to_latex(args[0], usePager) - else: - usage() - - -if __name__ == '__main__': - args = sys.argv[1:] - if '-d' not in args: - main() - else: - import pdb - pdb.run('main()') - - |