diff options
Diffstat (limited to 'sandbox/dkuhlman/Extract')
| -rw-r--r-- | sandbox/dkuhlman/Extract/Makefile | 64 | ||||
| -rwxr-xr-x | sandbox/dkuhlman/Extract/extract_doc.py | 436 | ||||
| -rw-r--r-- | sandbox/dkuhlman/Extract/extract_doc.txt | 222 |
3 files changed, 0 insertions, 722 deletions
diff --git a/sandbox/dkuhlman/Extract/Makefile b/sandbox/dkuhlman/Extract/Makefile deleted file mode 100644 index f0df1a5ef..000000000 --- a/sandbox/dkuhlman/Extract/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -# Makefile to process a file LaTeX with the Python LaTeX system. -# Optionally processes reStructuredText files. - -# -# Change the following to point to your Python source code. -# -PYTHON_SRC = /w1/Python/Python-2.3b2 -DOCUTILS_DIR = /w1/Python/DocUtils/docutils - -# -# Change the following to point to your Docutils installation. -# -DOCUTILSTOOLS_DIR = $(DOCUTILS_DIR)/tools -TRANSFORMDOCPY = $(DOCUTILSTOOLS_DIR)/python_latex.py \ - --documentclass=howto - -# -# Change these flags for your purposes. -# -#HTMLFLAGS= --image-type png --html -s 1 --favicon ../icons/pyfav.gif -#HTMLFLAGS= --iconserver ../icons --html -s 1 --favicon ../icons/pyfav.gif -HTMLFLAGS= --iconserver ../icons --html -s 1 \ - --favicon ../icons/pyfav.gif \ - --about $(PYTHON_SRC)/Doc/html/about_docutils.dat - -MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto - -PAPER = a4 - -# -# Change this to the name of your source file (without extension). -# -#SRC_NAME=pythonlatexsetup -ifndef SRC_NAME -$(error Must define SRC_NAME (no extension), e.g. make SRC_NAME=mysourcefile) -endif - -TARGETS = $(SRC_NAME)/$(SRC_NAME).html - -FIGURES = - -all: html - -html: $(TARGETS) $(FIGURES) - -$(SRC_NAME)/$(SRC_NAME).html: $(SRC_NAME).tex - $(MKHOWTO) $(HTMLFLAGS) $(SRC_NAME).tex - -# -# Remove or Comment out the following lines if your source file -# is a LaTeX file not a reST file. -# -$(SRC_NAME).tex: $(SRC_NAME).txt - $(TRANSFORMDOCPY) $(SRC_NAME).txt > $(SRC_NAME).tex - -clean: - rm -f *~ *.aux *.idx *.ilg *.ind *.log *.toc *.bkm *.syn \ -*.pla *.eps *.pdf *.ps *.lof *.l2h *.tex2 *.dvi - -rm -f $(SRC_NAME).tex - -rm -f $(SRC_NAME)/* - -rmdir $(SRC_NAME) - -rm -f $(SRC_NAME).tex - - 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()') - - diff --git a/sandbox/dkuhlman/Extract/extract_doc.txt b/sandbox/dkuhlman/Extract/extract_doc.txt deleted file mode 100644 index 167b103dc..000000000 --- a/sandbox/dkuhlman/Extract/extract_doc.txt +++ /dev/null @@ -1,222 +0,0 @@ - -:author: Dave Kuhlman -:address: dkuhlman@rexx.com \\\\ - http://www.rexx.com/~dkuhlman - -:revision: 1.0a -:date: July 22, 2003 - -:copyright: Copyright (c) 2003 Dave Kuhlman. - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, - copy, modify, merge, publish, distribute, sublicense, and/or - sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following - conditions: The above copyright notice and this permission - notice shall be included in all copies or substantial portions - of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT - WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT - LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES - OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR - OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE - SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -:abstract: This document describes extract_doc.py which is a - program for extracting documentation from Python source code - files and producing reStructuredText output. - - -============================================================= -*extract_doc.py* --- Extract Python Source Code Documentation -============================================================= - - -Description -=========== - -*extract_doc* extracts documentation embedded in Python source -code files. - -Currently, it generates reStructuredText. An extension that -generates LaTeX for the Python LaTeX documentation system is -being investigated. - -*extract_doc* is derived from and uses code in *pydoc.py* from the -Python standard library. - -One goal of *extract_doc* is to provide code that is simple enough -so that the implementation and the output it produces can be -customized for specific applications or by specific users. - - -Where to Get It -=============== - -You can find a distribution file for ``extract_doc`` at: - - http://www.rexx.com/~dkuhlman/extract_doc.zip - - -How to Use extract_doc -====================== - -Here is the usage information from `extract_doc`:: - - 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 - - -Command line flag descriptions ------------------------------- - --r, --rest Generate reStructuredText output. - --l, --latex Generate LaTeX for the Python LaTeX documentation - system. Not yet implemented. - --p, --pager Use a pager, else write to stdout. Selects a pager - and pushes generated output through the pager. On - my system it selects *less*. - --o, --over Generate over *and* under title adornment, else - generate under title adornment only. - - - -How to Modify *extract_doc* -=========================== - -*extract_doc* contains one important class: ReSTDoc. It is a -subclass of class Doc in module pydoc in the Python standard -library. As such, it should have followed other sub-classes of -class Doc closely. However, it does not. ReSTDoc is a fairly -radical re-write of TextDoc. This re-write had these goals: - -- Produce reStructuredText (rather than text or HTML). - -- Provide code that is simple, consistent, and clear enough so - that others can understand and modify it. - -Basically, I want it to produce reStructuredText and to enables -others to customize the reStructuredText that it produces for -their individual needs. - -The current class ``ReSTDoc`` produces reStructuredText. You can -try it for yourself. - -Here is a bit of guidance for the second aspect of the goal, i.e. -modifiability: - -- Output is accumulated by calling ``self.push(line)`` for each - line of text to be produced. - -- There are four functions that produce output. They are as - follows: - - - ``docmodule`` is called for the module. It is responsible for - producing the documentation for a module. - - - ``docclass`` is called for each class. It is responsible for - producing the documentation for a class. - - - ``docroutine`` -- Called for each method (in a class) and each - function (at top level in a module). It is responsible for - producing the documentation for a method or a function. - - - ``docother`` -- Called for data members. It is responsible for - producing the documentation for a data member. - -- Module ``inspect`` from the Python standard library is used to - obtain the internals of an object such as its members, to - determine the type of an object (e.g. method or function), - format the arguments for a function, etc. - -- Function getdoc in module ``pydoc`` is called to get the - documentation for an object, for example the documentation for a - module, a class, a method, or a function. - -- There is a method (emphasize) to emphasize a piece of text. It - adds asterisks around the text. - -In order to produce your own customized documentation extraction -capability, you might want to do the following: - -- Copy class ``ReSTDoc``. - -- Modify methods ``docmodule``, ``docclass``, ``docroutine``, and - ``docother`` in class ``ReSTDoc``. - -- copy function ``extract_to_rest``. - -- Modify function ``extract_to_rest``: - - - Add your own title, preferatory stuff, etc. Note where method - ``genTitle`` is called and where the "Generated by ..." - content is added. - - - Add your own end-of-doc content. Add this after the call to - ``formatter.document()``. - - -Related Work -============ - -*PySource* -- Python Source Reader ----------------------------------- - -This documentation extractor takes a very different approach. It -is *not* modelled on pydoc in the Python standard library. It -does not use the inspect module from the Python standard library. -(I grepped for "inspect" in ``sandbox/davidg/pysource_reader``.) -The documentation says that it: - - "... scans a parsed Python module, and returns an ordered tree - containing the names, docstrings (including attribute and - additional docstrings), and additional info ..." - -The approach followed by ``PySource`` appears more complex than -that of ``extract_doc, but also more powerful. I'm going to guess -that the start-up time for a simple-minded programmer (like me) to -begin modifying and customizing ``PySource`` for user specific -needs would be longer than for ``extract_doc``. - -I'd appreciate any comments and comparisons that others might -have. - -Credits -======= - -Thanks to the developers of Docutils, in particular, David -Goodger, project lead. - -Thanks to Ka-Ping Yee for *pydoc*. - - -See Also -======== - -`Docutils: Python Documentation Utilities`_ - -.. _`Docutils: Python Documentation Utilities`: - http://docutils.sourceforge.net/ - -`pydoc -- Documentation generator and online help system`_ - -.. _`pydoc -- Documentation generator and online help system`: - http://www.python.org/doc/current/lib/module-pydoc.html - - - |