diff options
Diffstat (limited to 'sandbox/dkuhlman')
| -rw-r--r-- | sandbox/dkuhlman/Docs/Makefile | 61 | ||||
| -rw-r--r-- | sandbox/dkuhlman/Docs/rstpythonlatex_intro.txt | 215 | ||||
| -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 | ||||
| -rw-r--r-- | sandbox/dkuhlman/README_docpy | 102 | ||||
| -rw-r--r-- | sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html | 1593 | ||||
| -rw-r--r-- | sandbox/dkuhlman/docutils/docutils/writers/python_latex.py | 1114 | ||||
| -rw-r--r-- | sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py | 698 | ||||
| -rw-r--r-- | sandbox/dkuhlman/docutils/test/README.test_python_latex | 36 | ||||
| -rw-r--r-- | sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py | 490 | ||||
| -rwxr-xr-x | sandbox/dkuhlman/docutils/tools/python_latex.py | 25 |
12 files changed, 0 insertions, 5056 deletions
diff --git a/sandbox/dkuhlman/Docs/Makefile b/sandbox/dkuhlman/Docs/Makefile deleted file mode 100644 index 6e6218f94..000000000 --- a/sandbox/dkuhlman/Docs/Makefile +++ /dev/null @@ -1,61 +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 - -MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto - -PAPER = a4 - -# -# Change this to the name of your source file (without extension). -# -#SRC_NAME=zip-ls -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/Docs/rstpythonlatex_intro.txt b/sandbox/dkuhlman/Docs/rstpythonlatex_intro.txt deleted file mode 100644 index cc37d6562..000000000 --- a/sandbox/dkuhlman/Docs/rstpythonlatex_intro.txt +++ /dev/null @@ -1,215 +0,0 @@ - -:author: Dave Kuhlman -:revision: 1.0a -:date: July 1, 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 a Docutils writer for use with - Python LaTeX and the Python project's documentation tools. - - -============================================== -Introduction to the Documenting Python Writer -============================================== - - -------------- -What It Does -------------- - -This writer for Docutils generates LaTeX suitable for -input to the documentation system described in `Documenting -Python`_ - -.. _`Documenting Python`: http://www.python.org/dev/doc/devel/doc/doc.html - - ---------------- -Where to Get It ---------------- - -This writer is not yet part of the Docutils distribution. Until -it is, you can find it at -`"A Docutils writer for the Documenting Python system"`_. - -.. _`"A Docutils writer for the Documenting Python system"`: - http://www.rexx.com/~dkuhlman/#docutils_pythonlatex - - --------------- -How to Use It --------------- - -Conversion has several steps: - -1. Run the writer -- Run *documenting_python.py* in - *docutils/tools*, for example:: - - $ docutils/tools/python_latex.py --documentclass=howto rstpythonlatex_intro.txt - - There is one option: - - - --documentclass=class - - Selects the template type from Doc/templates in the Python - source distribution. Possible values are ``howto``, - ``manual``, and ``module``. The ``module`` document type is - not yet implemented. See the Doc/templates subdirectory in the - Python Source code distribution for samples of these document - types. - - .. ("module" too, according to the writer's settings_spec. Or should - "module" be removed from the writer?) - -2. Run the "Documenting Python" document processor. - - -Here is a Makefile that performs these two steps. It was used to -convert the document that you are currently reading:: - - # 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 - - MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto - - PAPER = a4 - - # - # Change this to the name of your source file (without extension). - # - #SRC_NAME=zip-ls - 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 - - -Run this Makefile with the following commands:: - - $ make SRC_NAME=rstpythonlatex_intro clean - $ make SRC_NAME=rstpythonlatex_intro - - - - ------------------------------- -Special Formatting Constructs ------------------------------- - -See the companion document 'Quick reStructuredText for -"Documenting Python"' for additional mark-up that can be used when -generating LaTeX for "Documenting Python". It is included in the -distribution file for this writer. - -The first section of that document has information specific to the -generation of LaTeX for Documenting Python. - -In addition, that document also adds another column to the -specification tables. This additional column describes the LaTeX -commands generated by this writer. - - ------------------ -Acknowledgements ------------------ - -Thanks to the Docutils project members for Docutils. In -particular, thanks to project coordinator David Goodger. - -Thanks to Engelbert Gruber for the implementation of the LaTeX -writer. That implementation formed the starting point for this -writer. He should get much of the credit for this writer also, -however, any bugs were likely introduced by me. - -Thanks to Fred Drake (and many more I'm sure) for the Python -documentation tools, the Python documentation project, and the -Python documentation itself. - ---------- -See Also ---------- - -`The Docutils Home Page`_ - -.. _`The Docutils Home Page`: http://docutils.sourceforge.net/ - - -`The Python home page`_ - -.. _`The Python home page`: http://www.python.org/ - - -`The documentation on the Documenting Python system`_ - -.. _`The documentation on the Documenting Python system`: - http://www.python.org/dev/doc/devel/doc/doc.html - -`"A Docutils writer for the Documenting Python system"`_ - -.. _`"A Docutils writer for the Documenting Python system"`: - http://www.rexx.com/~dkuhlman/#docutils_pythonlatex - - 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 - - - diff --git a/sandbox/dkuhlman/README_docpy b/sandbox/dkuhlman/README_docpy deleted file mode 100644 index f5dfec768..000000000 --- a/sandbox/dkuhlman/README_docpy +++ /dev/null @@ -1,102 +0,0 @@ -======================================================= -Python LaTeX -- reStructuredText for Documenting Python -======================================================= - - -What it does -- Python LaTeX generates LaTeX suitable as input to -the "Documenting Python" system. This system is described at: - - http://www.python.org/dev/doc/devel/doc/doc.html - - -Installation ------------- - -If you have a standard Docutils installation, then you should be -able to go to the parent directory of the ``docutils`` directory, -then do the following:: - - unzip rstdocpy-1.0b.zip - -This will create (overlay) the following files:: - - README_docpy - Docs/Makefile - Docs/pythonlatex_intro.txt - docutils/docs/rst/docpy.html - docutils/docutils/writers/python_latex.py - docutils/tools/python_latex.py - -In order to use the above files in place, you may have to do -something like:: - - export PYTHONPATH=/w1/Python/DocUtils/docutils:$PYTHONPATH - -You will also need the "Documenting Python" tools installed. They -are in the ``Doc`` directory of the Python source code -distribution. - - -Testing -------- - -After the above installation, you should be able to go to the -``Msgs`` directory and convert the document ``docpy_intro.rst``. - -First, edit the file ``Msgs/Makefile``. Change the path that -points to the location where the Python source code is installed. -Then type:: - - cd Msgs - make clean - make - - -Documentation -------------- - -The file ``Msgs/docpy_intro.rst`` contains an introduction. - -See the companion document 'Quick reStructuredText for -"Documenting Python"' (docutils/docs/rst/docpy.html) for -additional mark-up that can be used when generating LaTeX for -"Documenting Python". The first section of this document has -information specific to the generation of LaTeX for Documenting -Python. In addition, that document also adds another column to the -specification tables. This additional column describes the LaTeX -commands generated by this writer. - - -More Information ----------------- - -Find out more about Docutils at:: - - http://docutils.sourceforge.net/ - -More information about the Documenting Python system is at:: - - http://www.python.org/dev/doc/devel/doc/doc.html - - -Acknowledgements ------------------ - -Thanks to the Docutils project members for Docutils. In -particular, thanks to project coordinator David Goodger. - -Thanks to Engelbert Gruber for the implementation of the latex -writer. That implementation formed the starting point for this -writer. He should get much of the credit for this writer also, -however, any bugs were likely introduced by me. - - -Contact -------- - -Please let me know about suggestions and problems:: - - Dave Kuhlman - dkuhlman@rexx.com - http://www.rexx.com/~dkuhlman - diff --git a/sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html b/sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html deleted file mode 100644 index 99bbd5611..000000000 --- a/sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html +++ /dev/null @@ -1,1593 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> - <head> - <title>Quick reStructuredText</title> - - <style type="text/css"><!-- - a.backref { text-decoration: none ; color: black } - --></style> - - </head> - - <body> - <h1>Quick <i>re</i><font -size="+4"><tt>Structured</tt></font><i>Text</i> for "Documenting -Python"</h1> - - <!-- Caveat: if you're reading the HTML for the examples, --> - <!-- beware that it was hand-generated, not by Docutils/ReST. --> - - <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" - >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> - <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-06-10</em> - - <blockquote> - <p>Copyright: This document has been placed in the public domain. - </blockquote> - - - <p>The full details of the markup may be found on the - <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> - page. This document is just intended as a reminder. - - <p>Links that look like "(<a href="#details">details</a>)" point - into the HTML version of the full <a - href="../../spec/rst/reStructuredText.html">reStructuredText - specification</a> document. These are relative links; if they - don't work, please use the <a - href="http://docutils.sourceforge.net/docs/rst/quickref.html" - >master "Quick reStructuredText"</a> document. - - <h2><a name="contents">Contents</a></h2> - - <ul> - <li><a href="#docpy">"Documenting Python"</a></li> - <li><a href="#inline-markup">Inline Markup</a></li> - <li><a href="#escaping">Escaping with Backslashes</a></li> - <li><a href="#section-structure">Section Structure</a></li> - <li><a href="#paragraphs">Paragraphs</a></li> - <li><a href="#bullet-lists">Bullet Lists</a></li> - <li><a href="#enumerated-lists">Enumerated Lists</a></li> - <li><a href="#definition-lists">Definition Lists</a></li> - <li><a href="#field-lists">Field Lists</a></li> - <li><a href="#option-lists">Option Lists</a></li> - <li><a href="#literal-blocks">Literal Blocks</a></li> - <li><a href="#block-quotes">Block Quotes</a></li> - <li><a href="#doctest-blocks">Doctest Blocks</a></li> - <li><a href="#tables">Tables</a></li> - <li><a href="#transitions">Transitions</a></li> - <li><a href="#explicit-markup">Explicit Markup</a> - <ul> - <li><a href="#footnotes">Footnotes</a></li> - <li><a href="#citations">Citations</a></li> - <li><a href="#hyperlink-targets">Hyperlink Targets</a> - <ul> - <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> - <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> - <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> - <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> - </ul></li> - <li><a href="#directives">Directives</a></li> - <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> - <li><a href="#comments">Comments</a></li> - </ul></li> - <li><a href="#getting-help">Getting Help</a></li> - </ul> - - <h2><a href="#contents" name="docpy" class="backref" - >Documenting Python</a></h2> - - <h3>Introduction</h3> - - <p>What it does -- It generates LaTeX suitable as input to the - "Documenting Python" system.</p> - - <p>How to run it: - - <pre> - $ docutils/tools/documenting_python.py --documentclass=howto infile.rst - </pre> - - <h3>Command-line options</h3> - - <dl> - - <dt>documentclass</dt> - <dd> - <ul> - - <li> Controls rusulting document class.</li> - - <li>Allowed values are "manual" and "howto".</li> - - <li>Default is "howto".</li> - - <li>Generates "\documentclass{manual}" or - "\documentclass{howto}".</li> - - </ul> - </dd> - - </dl> - - <h3>The heading section and controlling it</h3> - - <p>The following docinfo items, fields, and topics are - supported:</p> - - <ul> - - <li>:author: -- Generates "\author{}"..</li> - - <li>:date: -- Generates "\date{}".</li> - - <li>:revisision: -- Generates "release{}".</li> - - <li>:copyright: -- Generated at the beginning of the document.</li> - - <li>:abstract: -- Generates: - - <pre> - \begin{abstract} - \noindent - - [stuff] - \end{abstract} - </pre> - </li> - - <li>[The first] title -- Generates "\title{}". Note: I don't - understand the title promotion stuff. I'm guessing that I - have a bug here that will be discovered when we try a - different input (rST) document.</li> - - </ul> - - <p><strong>Example:</strong> -- Here is (the first few lines - of) a sample input rST file:</p> - - <pre> - :author: Dave Kuhlman - :date: 2003/06/05 - :revision: 1.27 - - :copyright: This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. - - :abstract: This is a test document, containing at least one - example of each reStructuredText construct. - - ====================================== - reStructuredText Test Document (title) - ====================================== - o - o - o - </pre> - - <p>If we run the above through this command:</p> - - <pre> - $ ../docutils/tools/documenting_python.py --documentclass=howto testdocpy1.rst - </pre> - - <p>And, here is what the above rST would generate:</p> - - <pre> - \documentclass{howto} - %% generator Docutils: http://docutils.sourceforge.net/ - \title{reStructuredText Test Document (title)} - \release{1.27} - \date{2003/06/05} - \author{Dave Kuhlman} - \begin{document} - \maketitle - \ifhtml - \chapter*{Front Matter\label{front}} - \fi - - This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. - \begin{abstract} - \noindent - - This is a test document, containing at least one - example of each reStructuredText construct. - \end{abstract} - \tableofcontents - o - o - o - </pre> - - <h3>The "See Also" section</h3> - - <p>If a section title matches the string "see also" (case - insensitive, then hyperlinks are treated slightly differently. - In particular, we generate "\seeurl{}".</p> - - - <h2><a href="#contents" name="inline-markup" class="backref" - >Inline Markup</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details</a>) - - <p>Inline markup allows words and phrases within text to have - character styles (like italics and boldface) and functionality - (like hyperlinks). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th>Plain text - <th>Typical result - <th>Notes - <th>Doc Py - </thead> - <tbody> - <tr valign="top"> - <td nowrap><samp>*emphasis*</samp> - <td><em>emphasis</em> - <td>Normally rendered as italics. - <td><pre>\emph{some text}</pre></td> - - <tr valign="top"> - <td nowrap><samp>**strong emphasis**</samp> - <td><strong>strong emphasis</strong> - <td>Normally rendered as boldface. - <td><pre>\strong{some text}</pre></td> - - <tr valign="top"> - <td nowrap><samp>`interpreted text`</samp> - <td>(see note at right) - <td>The rendering and <em>meaning</em> of interpreted text is - domain- or application-dependent. It can be used for things - like index entries or explicit descriptive markup (like program - identifiers). - - <tr valign="top"> - <td nowrap><samp>``inline literal``</samp> - <td><code>inline literal</code> - <td>Normally rendered as monospaced text. Spaces should be - preserved, but line breaks will not be. - <td> - <p> Generates \code{word}, if no embedded whitespace. Generates - \samp{some text}, if there is embedded whitespace.</p> - </td> - - <tr valign="top"> - <td nowrap><samp>reference_</samp> - <td><a href="#hyperlink-targets">reference</a> - <td>A simple, one-word hyperlink reference. See <a - href="#hyperlinks" >Hyperlinks</a>. - <td> - <pre>\ulink{label}{url}</pre> - <p>In "See Also" section:</p> - <pre>\seeurl{url}{label}</pre> - </td> - - <tr valign="top"> - <td nowrap><samp>`phrase reference`_</samp> - <td><a href="#hyperlink-targets">phrase reference</a> - <td>A hyperlink reference with spaces or punctuation needs to be - quoted with backquotes. See <a - href="#hyperlink-targets">Hyperlinks</a>. - <td> - <pre>\ulink{label}{url}</pre> - <p>In "See Also" section:</p> - <pre>\seeurl{url}{label}</pre> - </td> - - <tr valign="top"> - <td nowrap><samp>anonymous__</samp> - <td><a href="#hyperlink-targets">anonymous</a> - <td>With two underscores instead of one, both simple and phrase - references may be anonymous (the reference text is not repeated - at the target). See <a - href="#hyperlink-targets">Hyperlinks</a>. - - <tr valign="top"> - <td nowrap><samp>_`inline internal target`</samp> - <td><a name="inline-internal-target">inline internal target</a> - <td>A crossreference target within text. - See <a href="#hyperlink-targets">Hyperlinks</a>. - - <tr valign="top"> - <td nowrap><samp>|substitution reference|</samp> - <td>(see note at right) - <td>The result is substituted in from the <a - href="#substitution-references-and-definitions">substitution - definition</a>. It could be text, an image, a hyperlink, or a - combination of these and others. - - <tr valign="top"> - <td nowrap><samp>footnote reference [1]_</samp> - <td>footnote reference <sup><a href="#footnotes">1</a></sup> - <td>See <a href="#footnotes">Footnotes</a>. - - <tr valign="top"> - <td nowrap><samp>citation reference [CIT2002]_</samp> - <td>citation reference <a href="#citations">[CIT2002]</a> - <td>See <a href="#citations">Citations</a>. - - <tr valign="top"> - <td nowrap><samp>http://docutils.sf.net/</samp> - <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> - <td>A standalone hyperlink. - <td><pre>\url{http://docutils.sf.net/}</pre></td> - - </table> - - <p>Asterisk, backquote, vertical bar, and underscore are inline - delimiter characters. Asterisk, backquote, and vertical bar act - like quote marks; matching characters surround the marked-up word - or phrase, whitespace or other quoting is required outside them, - and there can't be whitespace just inside them. If you want to use - inline delimiter characters literally, <a href="#escaping">escape - (with backslash)</a> or quote them (with double backquotes; i.e. - use inline literals). - - <p>In detail, the reStructuredText specification says that in - inline markup, the following rules apply to start-strings and - end-strings (inline markup delimiters): - - <ol> - <li>The start-string must start a text block or be - immediately preceded by whitespace or any of - <samp>' " ( [ {</samp> or <samp><</samp>. - <li>The start-string must be immediately followed by non-whitespace. - <li>The end-string must be immediately preceded by non-whitespace. - <li>The end-string must end a text block (end of document or - followed by a blank line) or be immediately followed by whitespace - or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> - or <samp>></samp>. - <li>If a start-string is immediately preceded by one of - <samp>' " ( [ {</samp> or <samp><</samp>, it must not be - immediately followed by the corresponding character from - <samp>' " ) ] }</samp> or <samp>></samp>. - <li>An end-string must be separated by at least one - character from the start-string. - <li>An <a href="#escaping">unescaped</a> backslash preceding a - start-string or end-string will disable markup recognition, except - for the end-string of inline literals. - </ol> - - <p>Also remember that inline markup may not be nested (well, - except that inline literals can contain any of the other inline - markup delimiter characters, but that doesn't count because - nothing is processed). - - <h2><a href="#contents" name="escaping" class="backref" - >Escaping with Backslashes</a></h2> - - <p>(<a - href="../../spec/rst/reStructuredText.html#backslashes">details</a>) - - <p>reStructuredText uses backslashes ("\") to override the special - meaning given to markup characters and get the literal characters - themselves. To get a literal backslash, use an escaped backslash - ("\\"). For example: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Raw reStructuredText - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"><td> - <samp>*escape* ``with`` "\"</samp> - <td><em>escape</em> <samp>with</samp> "" - <tr valign="top"><td> - <samp>\*escape* \``with`` "\\"</samp> - <td>*escape* ``with`` "\" - <td><pre>$\backslash$</pre></td> - </table> - - <p>In Python strings it will, of course, be necessary - to escape any backslash characters so that they actually - <em>reach</em> reStructuredText. - The simplest way to do this is to use raw strings: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Python string - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"><td> - <samp>r"""\*escape* \`with` "\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\\*escape* \\`with` "\\\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\*escape* \`with` "\\""""</samp> - <td><em>escape</em> with "" - </table> - - <h2><a href="#contents" name="section-structure" class="backref" - >Section Structure</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#sections">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>=====</samp> -<br><samp>Title</samp> -<br><samp>=====</samp> -<br><samp>Subtitle</samp> -<br><samp>--------</samp> -<br><samp>Titles are underlined (or over-</samp> -<br><samp>and underlined) with a printing</samp> -<br><samp>nonalphanumeric 7-bit ASCII</samp> -<br><samp>character. Recommended choices</samp> -<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> -<br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text.</samp> - - <td> - <font size="+2"><strong>Title</strong></font> - <p><font size="+1"><strong>Subtitle</strong></font> - <p>Titles are underlined (or over- - and underlined) with a printing - nonalphanumeric 7-bit ASCII - character. Recommended choices - are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". - The underline/overline must be at - least as long as the title text. -<td> -\chapter{Title}<br/> -\section{Subtitle}<br/> -\subsection{Subsubtitle} -</td> - </table> - - <h2><a href="#contents" name="paragraphs" class="backref" - >Paragraphs</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#paragraphs">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>This is a paragraph.</samp> - -<p><samp>Paragraphs line up at their left</samp> -<br><samp>edges, and are normally separated</samp> -<br><samp>by blank lines.</samp> - - <td> - <p>This is a paragraph. - - <p>Paragraphs line up at their left edges, and are normally - separated by blank lines. - - <td> - <p>This is a paragraph. - - <p>Paragraphs line up at their left edges, and are normally - separated by blank lines. - </td> - - </table> - - <h2><a href="#contents" name="bullet-lists" class="backref" - >Bullet Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#bullet-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Bullet lists:</samp> - -<p><samp>- This is item 1</samp> -<br><samp>- This is item 2</samp> - -<p><samp>- Bullets are "-", "*" or "+".</samp> -<br><samp> Continuing text must be aligned</samp> -<br><samp> after the bullet and whitespace.</samp> - -<p><samp>Note that a blank line is required</samp> -<br><samp>before the first item and after the</samp> -<br><samp>last, but is optional between items.</samp> - <td>Bullet lists: - <ul> - <li>This is item 1 - <li>This is item 2 - <li>Bullets are "-", "*" or "+". - Continuing text must be aligned - after the bullet and whitespace. - </ul> - <p>Note that a blank line is required before the first - item and after the last, but is optional between items. -<td> -<pre> -\begin{itemize} - -\item This is item 1 - -\item This is item 2 - -\end{itemize} -</pre> -<p>Note: Embedded lists are supported.</p> -</td> - </table> - - <h2><a href="#contents" name="enumerated-lists" class="backref" - >Enumerated Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#enumerated-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Enumerated lists:</samp> - -<p><samp>3. This is the first item</samp> -<br><samp>4. This is the second item</samp> -<br><samp>5. Enumerators are arabic numbers,</samp> -<br><samp> single letters, or roman numerals</samp> -<br><samp>6. List items should be sequentially</samp> -<br><samp> numbered, but need not start at 1</samp> -<br><samp> (although not all formatters will</samp> -<br><samp> honour the first index).</samp> - <td>Enumerated lists: - <ol type="1"> - <li value="3">This is the first item - <li>This is the second item - <li>Enumerators are arabic numbers, single letters, - or roman numerals - <li>List items should be sequentially numbered, - but need not start at 1 (although not all - formatters will honour the first index). - </ol> -<td> -<pre> -\begin{enumerate} - -\item This is item 1 - -\item This is item 2 - -\end{enumerate} -</pre> -<p>Note: Embedded lists are supported.</p> -</td> - </table> - - <h2><a href="#contents" name="definition-lists" class="backref" - >Definition Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#definition-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Definition lists:</samp> -<br> -<br><samp>what</samp> -<br><samp> Definition lists associate a term with</samp> -<br><samp> a definition.</samp> -<br> -<br><samp>how</samp> -<br><samp> The term is a one-line phrase, and the</samp> -<br><samp> definition is one or more paragraphs or</samp> -<br><samp> body elements, indented relative to the</samp> -<br><samp> term. Blank lines are not allowed</samp> -<br><samp> between term and definition.</samp> - <td>Definition lists: - <dl> - <dt><strong>what</strong> - <dd>Definition lists associate a term with - a definition. - - <dt><strong>how</strong> - <dd>The term is a one-line phrase, and the - definition is one or more paragraphs or - body elements, indented relative to the - term. Blank lines are not allowed - between term and definition. - </dl> -<td><pre> -\begin{description} - -\item[label 1]Some descriptive text. - -\item[label 2]More descriptive text. - -\end{description} -</pre></td> - </table> - - <h2><a href="#contents" name="field-lists" class="backref" - >Field Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#field-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>:Authors:</samp> -<br><samp> Tony J. (Tibs) Ibbs,</samp> -<br><samp> David Goodger</samp> - -<p><samp> (and sundry other good-natured folks)</samp> - -<p><samp>:Version: 1.0 of 2001/08/08</samp> -<br><samp>:Dedication: To my father.</samp> - <td> - <table> - <tr valign="top"> - <td><strong>Authors:</strong> - <td>Tony J. (Tibs) Ibbs, - David Goodger - <tr><td><td>(and sundry other good-natured folks) - <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 - <tr><td><strong>Dedication:</strong><td>To my father. - </table> - </table> - - <p>Field lists are used as part of an extension syntax, such as - options for <a href="#directives">directives</a>, or database-like - records meant for further processing. Field lists may also be - used as generic two-column table constructs in documents. - - <h2><a href="#contents" name="option-lists" class="backref" - >Option Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#option-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> --a command-line option "a" -<br>-b file options can have arguments -<br> and long descriptions -<br>--long options can be long also -<br>--input=file long options can also have -<br> arguments -<br>/V DOS/VMS-style options too -</samp> - - <td> - <table border="0" width="100%"> - <tbody valign="top"> - <tr> - <td width="30%"><p><samp>-a</samp> - <td><p>command-line option "a" - <tr> - <td><p><samp>-b <i>file</i></samp> - <td><p>options can have arguments and long descriptions - <tr> - <td><p><samp>--long</samp> - <td><p>options can be long also - <tr> - <td><p><samp>--input=<i>file</i></samp> - <td><p>long options can also have arguments - <tr> - <td><p><samp>/V</samp> - <td><p>DOS/VMS-style options too - </table> -<td><pre> -\programopt{-a} -\longprogramopt{long} -\programopt{/V} -</pre></td> - </table> - - <p>There must be at least two spaces between the option and the - description. - - <h2><a href="#contents" name="literal-blocks" class="backref" - >Literal Blocks</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#literal-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>A paragraph containing only two colons</samp> -<br><samp>indicates that the following indented</samp> -<br><samp>text is a literal block.</samp> -<br> -<br><samp>::</samp> -<br> -<br><samp> Whitespace, newlines, blank lines, and</samp> -<br><samp> all kinds of markup (like *this* or</samp> -<br><samp> \this) is preserved by literal blocks.</samp> -<br> -<br><samp> The paragraph containing only '::'</samp> -<br><samp> will be omitted from the result.</samp> -<br> -<br><samp>The ``::`` may be tacked onto the very</samp> -<br><samp>end of any paragraph. The ``::`` will be</samp> -<br><samp>omitted if it is preceded by whitespace.</samp> -<br><samp>The ``::`` will be converted to a single</samp> -<br><samp>colon if preceded by text, like this::</samp> -<br> -<br><samp> It's very convenient to use this form.</samp> -<br> -<br><samp>Literal blocks end when text returns to</samp> -<br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like::</samp> -<br> -<br><samp> We start here</samp> -<br><samp> and continue here</samp> -<br><samp> and end here.</samp> -<br> -<br><samp>is possible.</samp> - - <td> - <p>A paragraph containing only two colons -indicates that the following indented -text is a literal block. - - <pre> - Whitespace, newlines, blank lines, and - all kinds of markup (like *this* or - \this) is preserved by literal blocks. - - The paragraph containing only '::' - will be omitted from the result.</pre> - - <p>The <samp>::</samp> may be tacked onto the very -end of any paragraph. The <samp>::</samp> will be -omitted if it is preceded by whitespace. -The <samp>::</samp> will be converted to a single -colon if preceded by text, like this: - - <pre> - It's very convenient to use this form.</pre> - - <p>Literal blocks end when text returns to -the preceding paragraph's indentation. -This means that something like: - - <pre> - We start here - and continue here - and end here.</pre> - - <p>is possible. -<td><pre> - - -A paragraph containing only two colons -indicates that the following indented -text is a literal block. - -\begin{verbatim} - Whitespace, newlines, blank lines, and - all kinds of markup (like *this* or - \this) is preserved by literal blocks. - - The paragraph containing only '::' - will be omitted from the result. -\end{verbatim} - -The <samp>::</samp> may be tacked onto the very -end of any paragraph. The <samp>::</samp> will be -omitted if it is preceded by whitespace. -The <samp>::</samp> will be converted to a single -colon if preceded by text, like this: - -\begin{verbatim} - It's very convenient to use this form. -\end{verbatim} - -Literal blocks end when text returns to -the preceding paragraph's indentation. -This means that something like: - -\begin{verbatim} - We start here - and continue here - and end here. -\end{verbatim} - -is possible. - - -</pre></td> - </table> - - <h2><a href="#contents" name="block-quotes" class="backref" - >Block Quotes</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#block-quotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Block quotes are just:</samp> - -<p><samp> Indented paragraphs,</samp> - -<p><samp> and they may nest.</samp> - <td> - Block quotes are just: - <blockquote> - <p>Indented paragraphs, - <blockquote> - <p>and they may nest. - </blockquote> - </blockquote> -<td><pre> -Block quotes are just: - -\begin{quotation} -Indented paragraphs -\end{quotation} -</pre></td> - </table> - - <h2><a href="#contents" name="doctest-blocks" class="backref" - >Doctest Blocks</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#doctest-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp>Doctest blocks are interactive -<br>Python sessions. They begin with -<br>"``>>>``" and end with a blank line.</samp> - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - - <td> - <p>Doctest blocks are interactive - Python sessions. They begin with - "<samp>>>></samp>" and end with a blank line. - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> -<td><pre> -\begin{verbatim} -<samp>>>> print "This is a doctest block." -\end{verbatim} -</pre></td> - </table> - - <p>"The <a - href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a> - module searches a module's docstrings for text that looks like an - interactive Python session, then executes all such sessions to - verify they still work exactly as shown." (From the doctest docs.) - - <h2><a href="#contents" name="tables" class="backref" - >Tables</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#tables">details</a>) - - <p>There are two syntaxes for tables in reStructuredText. Grid - tables are complete but cumbersome to create. Simple tables are - easy to create but limited (no row spans, etc.).</p> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>Grid table:</samp></p> - -<p><samp>+------------+------------+-----------+</samp> -<br><samp>| Header 1 | Header 2 | Header 3 |</samp> -<br><samp>+============+============+===========+</samp> -<br><samp>| body row 1 | column 2 | column 3 |</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 2 | Cells may span columns.|</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 3 | Cells may | - Cells |</samp> -<br><samp>+------------+ span rows. | - contain |</samp> -<br><samp>| body row 4 | | - blocks. |</samp> -<br><samp>+------------+------------+-----------+</samp></p> - <td> - <p>Grid table:</p> - <table border="1"> - <tr valign="top"> - <th>Header 1 - <th>Header 2 - <th>Header 3 - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - <tr valign="top"> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - <tr valign="top"> - <td>body row 4 - </table> - -<td><pre> -Two-column table: - -\begin{tableii}{l|l}{character}{Heading 1} - {Heading 2} -\lineii{value 1-1}{value 1-2} -\lineii{value 2-1}{value 2-2} -\end{tableii} - -Three-column table: - -\begin{tableiii}{l|l|l}{character} - {Heading 1}{Heading 2}{Heading 3} -\lineiii{value 1-1}{value 1-2}{value 1-3} -\lineiii{value 2-1}{value 2-2}{value 2-3} -\end{tableii} - -</pre></td> - - <tr valign="top"> - <td> -<p><samp>Simple table:</samp></p> - -<p><samp>===== ===== ======</samp> -<br><samp> Inputs Output</samp> -<br><samp>------------ ------</samp> -<br><samp> A B A or B</samp> -<br><samp>===== ===== ======</samp> -<br><samp>False False False</samp> -<br><samp>True False True</samp> -<br><samp>False True True</samp> -<br><samp>True True True</samp> -<br><samp>===== ===== ======</samp></p> - - <td> - <p>Simple table:</p> - <table frame="border" rules="all"> - <colgroup> - <col colwidth="31%" /> - <col colwidth="31%" /> - <col colwidth="38%" /> - </colgroup> - <thead valign="bottom"> - <tr> - <th colspan="2">Inputs - <th>Output - <tr> - <th>A - <th>B - <th>A or B - <tbody valign="top"> - <tr> - <td>False - <td>False - <td>False - <tr> - <td>True - <td>False - <td>True - <tr> - <td>False - <td>True - <td>True - <tr> - <td>True - <td>True - <td>True - </table> - - <td> - <p>Notes and limitations:</p> - <ul> - <li>Only regular tables supported. No COLSPAN or - ROWSPAN.</li> - <li>Tables with 2-columns, 3-columns, 4-columns, and - 5-columns are supported.</li> - <li>All columns are left-aligned.</li> - </ul> - </td> - </table> - - <h2><a href="#contents" name="transitions" class="backref" - >Transitions</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#transitions">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> -A transition marker is a horizontal line -<br>of 4 or more repeated punctuation -<br>characters.</samp> - - <p><samp>------------</samp> - - <p><samp>A transition should not begin or end a -<br>section or document, nor should two -<br>transitions be immediately adjacent.</samp> - - <td> - <p>A transition marker is a horizontal line - of 4 or more repeated punctuation - characters.</p> - - <hr> - - <p>A transition should not begin or end a - section or document, nor should two - transitions be immediately adjacent. -<td> - <p>A transition marker is a horizontal line - of 4 or more repeated punctuation - characters.</p> - - \hrule{} - - <p>A transition should not begin or end a - section or document, nor should two - transitions be immediately adjacent. -</td> - </table> - - <p>Transitions are commonly seen in novels and short fiction, as a - gap spanning one or more lines, marking text divisions or - signaling changes in subject, time, point of view, or emphasis. - - <h2><a href="#contents" name="explicit-markup" class="backref" - >Explicit Markup</a></h2> - - <p>Explicit markup blocks are used for constructs which float - (footnotes), have no direct paper-document representation - (hyperlink targets, comments), or require specialized processing - (directives). They all begin with two periods and whitespace, the - "explicit markup start". - - <h3><a href="#contents" name="footnotes" class="backref" - >Footnotes</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#footnotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Footnote references, like [5]_.</samp> - <br><samp>Note that footnotes may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [5] A numerical footnote. Note</samp> - <br><samp> there's no colon after the ``]``.</samp> - - <td> - Footnote references, like <sup><a href="#5">5</a></sup>. - Note that footnotes may get rearranged, e.g., to the bottom of - the "page". - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. - Note there's no colon after the <samp>]</samp>. - </table> - <td> -Footnote references, like\footnote{A numerical footnote. -Note there's no colon after the <samp>]</samp>.}. -Note that footnotes may get -rearranged, e.g., to the bottom of -the "page". - <tr valign="top"> - <td> - <samp>Autonumbered footnotes are</samp> - <br><samp>possible, like using [#]_ and [#]_.</samp> - <p><samp>.. [#] This is the first one.</samp> - <br><samp>.. [#] This is the second one.</samp> - - <p><samp>They may be assigned 'autonumber</samp> - <br><samp>labels' - for instance, - <br>[#fourth]_ and [#third]_.</samp> - - <p><samp>.. [#third] a.k.a. third_</samp> - <p><samp>.. [#fourth] a.k.a. fourth_</samp> - <td> - Autonumbered footnotes are possible, like using <sup><a - href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. - - <p>They may be assigned 'autonumber labels' - for instance, - <sup><a href="#fourth">4</a></sup> and <sup><a - href="#third">3</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. - <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. - <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> - <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> - </table> - <td> -<p>Autonumbered footnotes are possible, like using\footnote{This is -the first one.} and \footnote{This is the second one.}. </p> - -<p>They may be assigned 'autonumber labels' - for instance, -\footnote{a.k.a. third} and \footnote{a.k.a. fourth}. </p> - -<p>[Note: Re-ordering of footnotes is not supported in DocPy.]</p> - - </br></td> - - <tr valign="top"> - <td> - <samp>Auto-symbol footnotes are also</samp> - <br><samp>possible, like this: [*]_ and [*]_.</samp> - <p><samp>.. [*] This is the first one.</samp> - <br><samp>.. [*] This is the second one.</samp> - - <td> - Auto-symbol footnotes are also - possible, like this: <sup><a href="#symbol1">*</a></sup> - and <sup><a href="#symbol2">†</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote - <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. - </table> - - <td> - [Not supported in DocPy.] - - </table> - - <p>The numbering of auto-numbered footnotes is determined by the - order of the footnotes, not of the references. For auto-numbered - footnote references without autonumber labels - ("<samp>[#]_</samp>"), the references and footnotes must be in the - same relative order. Similarly for auto-symbol footnotes - ("<samp>[*]_</samp>"). - - <h3><a href="#contents" name="citations" class="backref" - >Citations</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#citations">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Citation references, like [CIT2002]_.</samp> - <br><samp>Note that citations may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [CIT2002] A citation</samp> - <br><samp> (as often used in journals).</samp> - - <p><samp>Citation labels contain alphanumerics,</samp> - <br><samp>underlines, hyphens and fullstops.</samp> - <br><samp>Case is not significant.</samp> - - <p><samp>Given a citation like [this]_, one</samp> - <br><samp>can also refer to it like this_.</samp> - - <p><samp>.. [this] here.</samp> - - <td> - Citation references, like <a href="#cit2002">[CIT2002]</a>. - Note that citations may get rearranged, e.g., to the bottom of - the "page". - - <p>Citation labels contain alphanumerics, underlines, hyphens - and fullstops. Case is not significant. - - <p>Given a citation like <a href="#this">[this]</a>, one - can also refer to it like <a href="#this">this</a>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Citations: --> - <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation - (as often used in journals). - <tr><td><a name="this"><strong>[this]</strong></a><td> here. - </table> - - </table> - - <h3><a href="#contents" name="hyperlink-targets" class="backref" - >Hyperlink Targets</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details</a>) - - <h4><a href="#contents" name="external-hyperlink-targets" class="backref" - >External Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>External hyperlinks, like Python_.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <tr><td>Indirect hyperlinks, like - <a href="http://www.python.org">Python</a>. - <tr bgcolor="#99CCFF"><td><em>Call-out form</em> - <tr><td>External hyperlinks, like - <a href="#labPython"><i>Python</i></a>. - - <p><table> - <tr><td colspan="2"><hr> - <tr><td><a name="labPython"><i>Python:</i></a> - <td> <a href="http://www.python.org/">http://www.python.org/</a> - </table> - </table> - <td> - <p>External hyperlinks, like - \ulink{Python}{http://www.python.org/}.</p> - </table> - - <p>"<em>Fold-in</em>" is the representation typically used in HTML - documents (think of the indirect hyperlink being "folded in" like - ingredients into a cake), and "<em>call-out</em>" is more suitable for - printed documents, where the link needs to be presented explicitly, for - example as a footnote. - - <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" - >Internal Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td><samp>Internal crossreferences, like example_.</samp> - - <p><samp>.. _example:</samp> - - <p><samp>This is an example crossreference target.</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <!-- Note that some browsers may not like an "a" tag that --> - <!-- does not have any content, so we could arbitrarily --> - <!-- use the first word as content - *or* just trust to --> - <!-- luck! --> - <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> - <p><a name="example-foldin">This</a> is an example - crossreference target. - <tr><td bgcolor="#99CCFF"><em>Call-out form</em> - <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> - - <p><a name="example-callout"><i>example:</i></a> - <br>This is an example crossreference target. - </table> - - </table> - - <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" - >Indirect Hyperlink Targets</a></h4> - - <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Python_ is `my favourite -<br>programming language`__.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - - <p><samp>__ Python_</samp> - - <td> - <p><a href="http://www.python.org/">Python</a> is - <a href="http://www.python.org/">my favourite - programming language</a>. - - </table> - - <p>The second hyperlink target (the line beginning with - "<samp>__</samp>") is both an indirect hyperlink target - (<i>indirectly</i> pointing at the Python website via the - "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink - target</b>. In the text, a double-underscore suffix is used to - indicate an <b>anonymous hyperlink reference</b>. In an anonymous - hyperlink target, the reference text is not repeated. This is - useful for references with long text or throw-away references, but - the target should be kept close to the reference to prevent them - going out of sync. - - <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" - >Implicit Hyperlink Targets</a></h4> - - <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details</a>) - - <p>Section titles, footnotes, and citations automatically generate - hyperlink targets (the title text or footnote/citation label is - used as the hyperlink name). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Titles are targets, too</samp> - <br><samp>=======================</samp> - <br><samp>Implict references, like `Titles are</samp> - <br><samp>targets, too`_.</samp> - <td> - <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> - <p>Implict references, like <a href="#Title">Titles are - targets, too</a>. - </table> - - <h3><a href="#contents" name="directives" class="backref" - >Directives</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#directives">details</a>) - - <p>Directives are a general-purpose extension mechanism, a way of - adding support for new constructs without adding new syntax. For - a description of all standard directives, see <a - href="../../spec/rst/directives.html" >reStructuredText - Directives</a>. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp>For instance:</samp> - - <p><samp>.. image:: images/ball1.gif</samp> - - <td> - For instance: - <p><img src="images/ball1.gif" alt="ball1"> - </table> - - <h3><a href="#contents" name="substitution-references-and-definitions" - class="backref" >Substitution References and Definitions</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#substitution-definitions">details</a>) - - <p>Substitutions are like inline directives, allowing graphics and - arbitrary constructs within text. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp> -The |biohazard| symbol must be -used on containers used to -dispose of medical waste.</samp> - - <p><samp> -.. |biohazard| image:: biohazard.png</samp> - - <td> - - <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol - must be used on containers used to dispose of medical waste. - - </table> - - <h3><a href="#contents" name="comments" class="backref" - >Comments</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#comments">details</a>) - - <p>Any text which begins with an explicit markup start but doesn't - use the syntax of any of the constructs above, is a comment. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td><samp>.. This text will not be shown</samp> - <br><samp> (but, for instance, in HTML might be</samp> - <br><samp> rendered as an HTML comment)</samp> - - <td> - <!-- This text will not be shown --> - <!-- (but, for instance in HTML might be --> - <!-- rendered as an HTML comment) --> - -<td><pre> -% This text will not be shown -% (but, for instance, in HTML might be -% rendered as an HTML comment) -</pre></td> - <tr valign="top"> - <td> - <samp>An empty "comment" does not</samp> - <br><samp>"consume" following blocks.</samp> - <p><samp>..</samp> - <p><samp> So this block is not "lost",</samp> - <br><samp> despite its indentation.</samp> - <td> - An empty "comment" does not - "consume" following blocks. - <blockquote> - So this block is not "lost", - despite its indentation. - </blockquote> - </table> - - <h2><a href="#contents" name="getting-help" class="backref" - >Getting Help</a></h2> - - <p>Users who have questions or need assistance with Docutils or - reStructuredText should <a - href="mailto:docutils-users@lists.sourceforge.net" >post a - message</a> to the <a - href="http://lists.sourceforge.net/lists/listinfo/docutils-users" - >Docutils-Users mailing list</a>. The <a - href="http://docutils.sourceforge.net/" >Docutils project web - site</a> has more information. - - <p><hr> - <address> - <p>Authors: - <a href="http://www.tibsnjoan.co.uk/">Tibs</a> - (<a href="mailto:tony@lsl.co.uk"><tt>tony@lsl.co.uk</tt></a> or - <a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) - and David Goodger - (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) - </address> - <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> - </body> -</html> diff --git a/sandbox/dkuhlman/docutils/docutils/writers/python_latex.py b/sandbox/dkuhlman/docutils/docutils/writers/python_latex.py deleted file mode 100644 index 62f4c0363..000000000 --- a/sandbox/dkuhlman/docutils/docutils/writers/python_latex.py +++ /dev/null @@ -1,1114 +0,0 @@ -#!/usr/bin/env python - -""" -:Author: Dave Kuhlman -:Contact: dkuhlman@rexx.com -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. - -LaTeX2e document tree Writer. -""" - -__docformat__ = 'reStructuredText' - -# convention deactivate code by two # e.g. ##. - -import sys -import time -import re -import string -import urllib, urlparse -from docutils import writers, nodes, languages - -## from IPython.Shell import IPShellEmbed -## args = '' -## ipshell = IPShellEmbed(args, -## banner = 'Dropping into IPython', -## exit_msg = 'Leaving Interpreter, back to program.') - - -# To turn off debug printing, set to 0. -DEBUG_FLAG = 1 - -# Constants and globals: - -COMMENT_RE_SUB = re.compile('\n').sub -PROGRAMOPT_RE = re.compile('(--[_\-a-zA-Z0-9]+)') -EMAILADDR_RE = re.compile(r'[_\-a-zA-Z0-9.]+@[_\-a-zA-Z0-9.]+') -WEBADDR_RE = re.compile(r'http://[_\-a-zA-Z0-9./~]+') - -TABLE_MODE_NONE = 0 -TABLE_MODE_HEAD = 1 -TABLE_MODE_BODY = 2 - -class TableSpec: - def __init__(self): - self.columnCount = 0 - self.mode = TABLE_MODE_NONE - def getColumnCount(self): return self.columnCount - def setColumnCount(self, columnCount): self.columnCount = columnCount - def getMode(self): return self.mode - def setMode(self, mode): self.mode = mode - - -class Writer(writers.Writer): - - supported = ('latex','latex2e') - """Formats this writer supports.""" - - settings_spec = ( - 'Documenting Python LaTeX Specific Options', - 'The LaTeX "--output-encoding" default is "latin-1:strict".', - (('Specify documentclass (one of howto, manual, module). Default is "howto".', -# (('Specify documentclass (one of howto, manual). Default is "howto".', - ['--documentclass'], - {'default': 'howto', }), - )) - - #settings_defaults = {} - settings_defaults = {'output_encoding': 'latin-1'} - - output = None - """Final translated form of `document`.""" - - def translate(self): - visitor = DocPyTranslator(self.document) - self.document.walkabout(visitor) - #import pdb - #pdb.run('self.document.walkabout(visitor)', globals(), locals()) - self.output = visitor.astext() - - -class DocPyTranslator(nodes.NodeVisitor): - latex_head = '\\documentclass{%s}\n' - # add a generated on day , machine by user using docutils version. - generator = '\n%% generator -- Docutils: http://docutils.sourceforge.net/\n' \ - '%% writer -- documenting_python\n' \ - '%% generated on -- %s\n\n' % time.ctime() - - def __init__(self, document): - nodes.NodeVisitor.__init__(self, document) - self.docinfo = {} - self.settings = settings = document.settings - if self.settings.documentclass == 'module': - raise NotImplementedError, 'Error: module document type not yet implemented.' - self.head_prefix = [ - self.latex_head % (self.settings.documentclass, ), - #self.encoding, - #self.linking % (self.colorlinks, self.hyperlink_color, self.hyperlink_color), - # geometry and fonts might go into style.tex. - #self.geometry % (self.d_paper, self.d_margins), - # - self.generator, - '\\usepackage{html}\n', - ] - - # NOTE: Latex wants a date and an author, rst puts this into - # docinfo, so normally we donot want latex author/date handling. - # latex article has its own handling of date and author, deactivate. - self.latex_docinfo = 0 - self.head = [ ] - self.body_prefix = [] - # separate title, so we can appen subtitle. - self.title = "" - self.body = [] - self.body_suffix = ['\n'] - self.section_level = 0 - self.context = [] - self.topic_class = '' - # Flags to encode - # --------------- - # verbatim: to tell encode not to encode. - self.verbatim = 0 - # insert_newline: to tell encode to replace blanks by "~". - self.insert_none_breaking_blanks = 0 - # insert_newline: to tell encode to add latex newline. - self.insert_newline = 0 - # mbox_newline: to tell encode to add mbox and newline. - self.mbox_newline = 0 - - # inside literal block: no quote mangling. - self.literal = 0 - self.seealso = 0 - self.title_before_section = 0 - self.seen_section = 0 - - def pdebug(self, msg): - if DEBUG_FLAG >= 1: - self.body.append(msg) - - def encode(self, text): - """ - Encode special characters in `text` & return. - # $ % & ~ _ ^ \ { } - Escaping with a backslash does not help with backslashes, ~ and ^. - - < > are only available in math-mode (really ?) - $ starts math- mode. - AND quotes: - - """ - if self.verbatim: - return text - # compile the regexps once. do it here so one can see them. - # - # first the braces. - if not self.__dict__.has_key('encode_re_braces'): - self.encode_re_braces = re.compile(r'([{}])') - text = self.encode_re_braces.sub(r'{\\\1}',text) - if not self.__dict__.has_key('encode_re_bslash'): - # find backslash: except in the form '{\{}' or '{\}}'. - self.encode_re_bslash = re.compile(r'(?<!{)(\\)(?![{}]})') - # then the backslash: except in the form from line above: - # either '{\{}' or '{\}}'. - text = self.encode_re_bslash.sub(r'{\\textbackslash}', text) - - # then dollar - text = text.replace("$", '{\\$}') - # then all that needs math mode - text = text.replace("<", '{$<$}') - text = text.replace(">", '{$>$}') - # then - text = text.replace("&", '{\\&}') - text = text.replace("_", '{\\_}') - # the ^: - # * verb|^| does not work in mbox. - # * mathmode has wedge. hat{~} would also work. - text = text.replace("^", '{\\ensuremath{^\\wedge}}') - text = text.replace("%", '{\\%}') - text = text.replace("#", '{\\#}') - text = text.replace("~", '{\\~{}}') - if self.insert_newline: - # HACK: insert a blank before the newline, to avoid - # ! LaTeX Error: There's no line here to end. - text = text.replace("\n", '~\\\\\n') - elif self.mbox_newline: - text = text.replace("\n", '}\\\\\n\\mbox{') - if self.insert_none_breaking_blanks: - text = text.replace(' ', '~') - # unicode !!! - text = text.replace(u'\u2020', '{$\\dagger$}') - return text - - def attval(self, text, - whitespace=re.compile('[\n\r\t\v\f]')): - """Cleanse, encode, and return attribute value text.""" - return self.encode(whitespace.sub(' ', text)) - - def replace_email_addr(self, mo): - addr = mo.group(0) - outtext = '\\ulink{%s}{mailto:%s}' % (addr, addr) - return outtext - - def replace_web_addr(self, mo): - addr = mo.group(0) - outtext = '\\ulink{%s}{%s}' % (addr, addr) - return outtext - - def linkify(self, intext): - # If it looks like an email address, convert it to a "mailto" URL. - text1 = EMAILADDR_RE.sub(self.replace_email_addr, intext) - # If it looks like a URL, convert it to a ulink. - text2 = WEBADDR_RE.sub(self.replace_web_addr, text1) - return text2 - - def astext(self): - title = '\\title{%s}\n' % self.title - if self.docinfo.has_key('revision'): - self.head.append('\\release{%s}\n' % self.docinfo['revision']) - if self.docinfo.has_key('date'): - self.head.append('\\date{%s}\n' % self.docinfo['date']) - if self.docinfo.has_key('author'): - self.head.append('\\author{%s}\n' % self.docinfo['author']) - if self.docinfo.has_key('address'): - self.pdebug('%% [(astext) text: %s]\n' % self.docinfo['address']) - self.head.append('\\authoraddress{%s}\n' % \ - #self.linkify(self.cleanHref(self.docinfo['address']))) - self.cleanHref(self.linkify( - self.docinfo['address'])).replace('\n', '\\\\\n')) - self.body_prefix.append('\\maketitle\n') - self.body_prefix.append('\\ifhtml\n') - self.body_prefix.append('\\chapter*{Front Matter\\label{front}}\n') - self.body_prefix.append('\\fi\n') - if self.docinfo.has_key('copyright'): - self.body_prefix.append('\n%s\n' % self.docinfo['copyright']) - if self.docinfo.has_key('abstract'): - self.body_prefix.append('\\begin{abstract}\n\\noindent\n') - self.body_prefix.append('%s\n' % self.docinfo['abstract']) - self.body_prefix.append('\\end{abstract}\n') - self.body_prefix.append('\\tableofcontents\n') - result = ''.join( - self.head_prefix + - [title] + - self.head + - self.body_prefix + - self.body + - self.body_suffix) - return result - - def visit_Text(self, node): - self.body.append(self.encode(node.astext())) - - def depart_Text(self, node): - pass - - def visit_address(self, node): - self.visit_docinfo_item(node, 'address') - raise nodes.SkipNode - - def depart_address(self, node): - self.depart_docinfo_item(node) - - def visit_admonition(self, node, name): - self.body.append('\\begin{center}\\begin{sffamily}\n') - self.body.append('\\fbox{\\parbox{\\admonitionwidth}{\n') - self.body.append('\\textbf{\\large '+ self.language.labels[name] + '}\n'); - self.body.append('\\vspace{2mm}\n') - - - def depart_admonition(self): - self.body.append('}}\n') # end parbox fbox - self.body.append('\\end{sffamily}\n\\end{center}\n'); - - def visit_attention(self, node): - self.visit_admonition(node, 'attention') - - def depart_attention(self, node): - self.depart_admonition() - - def visit_author(self, node): - #self.pdebug('%% [(visit_author) node: %s]\n' % str(node)) - self.visit_docinfo_item(node, 'author') - raise nodes.SkipNode - - def depart_author(self, node): - self.depart_docinfo_item(node) - - def visit_authors(self, node): - # ignore. visit_author is called for each one - # self.visit_docinfo_item(node, 'author') - pass - - def depart_authors(self, node): - # self.depart_docinfo_item(node) - pass - - def visit_block_quote(self, node): - # If the block quote contains a single object and that object - # is a list, then generate a list not a block quote. - # This lets us indent lists. - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\begin{quote}\n') - - def depart_block_quote(self, node): - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\end{quote}\n') - - def visit_bullet_list(self, node): - self.body.append('\\begin{itemize}\n' ) - - def depart_bullet_list(self, node): - self.body.append('\\end{itemize}\n' ) - - def visit_enumerated_list(self, node): - self.body.append('\\begin{enumerate}\n' ) - - def depart_enumerated_list(self, node): - self.body.append('\\end{enumerate}\n') - - def visit_caption(self, node): - self.body.append('\\caption{' ) - - def depart_caption(self, node): - self.body.append('}') - - def visit_caution(self, node): - self.visit_admonition(node, 'caution') - - def depart_caution(self, node): - self.depart_admonition() - - def visit_citation(self, node): - self.visit_footnote(node) - - def depart_citation(self, node): - self.depart_footnote(node) - - def visit_title_reference(self, node): - # BUG title-references are what? - pass - - def depart_title_reference(self, node): - pass - - def visit_citation_reference(self, node): - pass - - def depart_citation_reference(self, node): - pass - - def visit_classifier(self, node): - pass - - def depart_classifier(self, node): - pass - - def visit_colspec(self, node): - pass - - def depart_colspec(self, node): - pass - - def visit_comment(self, node): - """Escape end of line by a ne comment start in comment text.""" - self.body.append('\n%% %s \n' % COMMENT_RE_SUB('\n% ', node.astext())) - raise nodes.SkipNode - - def visit_contact(self, node): - self.visit_docinfo_item(node, 'contact') - - def depart_contact(self, node): - self.depart_docinfo_item(node) - - def visit_copyright(self, node): - self.visit_docinfo_item(node, 'copyright') - raise nodes.SkipNode - - def depart_copyright(self, node): - self.depart_docinfo_item(node) - - def visit_danger(self, node): - self.visit_admonition(node, 'danger') - - def depart_danger(self, node): - self.depart_admonition() - - def visit_date(self, node): - ## self.pdebug('%% [(visit_date) node: %s]\n' % str(node)) - self.visit_docinfo_item(node, 'date') - raise nodes.SkipNode - - def depart_date(self, node): - self.depart_docinfo_item(node) - - def visit_decoration(self, node): - pass - - def depart_decoration(self, node): - pass - - def visit_definition(self, node): - #self.body.append('% [(visit_definition)]\n') - pass - - def depart_definition(self, node): - self.body.append('\n') - #self.body.append('%[(depart_definition)]\n') - - def visit_definition_list(self, node): - self.body.append( '\n\\begin{description}\n' ) - - def depart_definition_list(self, node): - self.body.append( '\\end{description}\n' ) - - def visit_definition_list_item(self, node): - #self.body.append('%[(visit_definition_list_item)]\n') - pass - - def depart_definition_list_item(self, node): - #self.body.append('%[(depart_definition_list_item)]\n') - pass - - def visit_description(self, node): - self.body.append( ' ' ) - - def depart_description(self, node): - pass - - def visit_docinfo(self, node): - self.docinfo = {} - - def depart_docinfo(self, node): - pass - - def visit_docinfo_item(self, node, name): - self.docinfo[name] = node.astext() - - def depart_docinfo_item(self, node): - pass - - def visit_doctest_block(self, node): - self.body.append('\\begin{verbatim}\n' ) - self.verbatim = 1 - - def depart_doctest_block(self, node): - self.body.append( '\n\\end{verbatim}\n' ) - self.verbatim = 0 - - def visit_document(self, node): - self.body_prefix.append('\\begin{document}\n') - - def depart_document(self, node): - if self.seealso: - self.body.append('\\end{seealso}\n') - self.body_suffix.append('\\end{document}\n') - - def visit_emphasis(self, node): - self.body.append('\\emph{') - - def depart_emphasis(self, node): - self.body.append('}') - - def visit_error(self, node): - self.visit_admonition(node, 'error') - - def depart_error(self, node): - self.depart_admonition() - - def visit_field(self, node): - # real output is done in siblings: _argument, _body, _name - raise nodes.SkipNode - pass - - def depart_field(self, node): - self.body.append('\n') - ##self.body.append('%[depart_field]\n') - - def visit_field_argument(self, node): - #self.pdebug('%% [(visit_field_argument) node: %s]\n' % str(node)) - #self.pdebug('% [visit_field_argument]\n') - pass - - def depart_field_argument(self, node): - #self.pdebug('% [(depart_field_argument)]\n') - pass - - def visit_field_body(self, node): - #self.pdebug('%% [(visit_field_body) node: %s]\n' % str(node)) - # BUG by attach as text we loose references. -## if self.docinfo and self.current_field_name: -## self.docinfo[self.current_field_name] += '%s \\\\\n' % node.astext() -## raise nodes.SkipNode - pass - - def depart_field_body(self, node): -## self.body.append( '\n' ) - pass - - def visit_field_list(self, node): -## if not self.docinfo: -## self.body.append('\\begin{quote}\n') -## self.body.append('\\begin{description}\n') - pass - - def depart_field_list(self, node): -## if not self.docinfo: -## self.body.append('\\end{description}\n') -## self.body.append('\\end{quote}\n') - pass - - def visit_field_name(self, node): -## self.pdebug('%% [(visit_field_name) content: %s]\n' % node.astext()) -## self.pdebug('%% [(visit_field_name) node: %s\n' % str(node)) -## self.docinfo[node.astext()] = '' -## self.current_field_name = node.astext() - pass - - def depart_field_name(self, node): - pass - - def visit_figure(self, node): - self.body.append( '\\begin{figure}\n' ) - - def depart_figure(self, node): - self.body.append( '\\end{figure}\n' ) - - def visit_footer(self, node): - self.context.append(len(self.body)) - - def depart_footer(self, node): - start = self.context.pop() - footer = (['\n\\begin{center}\small\n'] - + self.body[start:] + ['\n\\end{center}\n']) - self.body_suffix[:0] = footer - del self.body[start:] - - def visit_footnote(self, node): - notename = node['id'] - self.body.append('\\begin{figure}[b]') - self.body.append('\\hypertarget{%s}' % notename) - - def depart_footnote(self, node): - self.body.append('\\end{figure}\n') - - def visit_footnote_reference(self, node): - href = '' - if node.has_key('refid'): - href = node['refid'] - elif node.has_key('refname'): - href = self.document.nameids[node['refname']] - format = self.settings.footnote_references - if format == 'brackets': - suffix = '[' - self.context.append(']') - elif format == 'superscript': - suffix = '\\raisebox{.5em}[0em]{\\scriptsize' - self.context.append('}') - else: # shouldn't happen - raise AssertionError('Illegal footnote reference format.') - self.body.append('%s\\hyperlink{%s}{' % (suffix,href)) - - def depart_footnote_reference(self, node): - self.body.append('}%s' % self.context.pop()) - - def visit_generated(self, node): - pass - - def depart_generated(self, node): - pass - - def visit_header(self, node): - self.body.append('%% [(visit_header) node: %s\n' % str(node)) - self.context.append(len(self.body)) - - def depart_header(self, node): - start = self.context.pop() - self.body_prefix.append('\n\\verb|begin_header|\n') - self.body_prefix.extend(self.body[start:]) - self.body_prefix.append('\n\\verb|end_header|\n') - del self.body[start:] - - def visit_hint(self, node): - self.visit_admonition(node, 'hint') - - def depart_hint(self, node): - self.depart_admonition() - - def visit_image(self, node): - atts = node.attributes.copy() - href = atts['uri'] - ##self.body.append('\\begin{center}\n') - self.body.append('\n\\includegraphics{%s}\n' % href) - ##self.body.append('\\end{center}\n') - - def depart_image(self, node): - pass - - def visit_important(self, node): - self.visit_admonition(node, 'important') - - def depart_important(self, node): - self.depart_admonition() - - def visit_interpreted(self, node): - # @@@ Incomplete, pending a proper implementation on the - # Parser/Reader end. - self.visit_literal(node) - - def depart_interpreted(self, node): - self.depart_literal(node) - - def visit_label(self, node): - # footnote/citation label - self.body.append('[') - - def depart_label(self, node): - self.body.append(']') - - def visit_legend(self, node): - self.body.append('{\\small ') - - def depart_legend(self, node): - self.body.append('}') - - def visit_line_block(self, node): - """line-block: - * whitespace (including linebreaks) is significant - * inline markup is supported. - * serif typeface - """ - self.body.append('\\begin{flushleft}\n') - self.insert_none_breaking_blanks = 1 - self.line_block_without_mbox = 1 - if self.line_block_without_mbox: - self.insert_newline = 1 - else: - self.mbox_newline = 1 - self.body.append('\\mbox{') - - def depart_line_block(self, node): - if self.line_block_without_mbox: - self.insert_newline = 0 - else: - self.body.append('}') - self.mbox_newline = 0 - self.insert_none_breaking_blanks = 0 - self.body.append('\n\\end{flushleft}\n') - - def visit_list_item(self, node): - self.body.append('\\item ') - - def depart_list_item(self, node): - self.body.append('\n') - - def visit_literal(self, node): - ## self.literal = 1 - content = node.astext().strip() - if re.search('[ \t\n]', content): - self.body.append('\\samp{%s}' % content) - else: - self.body.append('\\code{%s}' % content) - raise nodes.SkipNode - - def depart_literal(self, node): - pass - - def visit_literal_block(self, node): - self.verbatim = 1 - self.body.append('\n\\begin{verbatim}\n') - - def depart_literal_block(self, node): - self.body.append('\n\\end{verbatim}\n') - self.verbatim = 0 - - def visit_meta(self, node): - self.body.append('[visit_meta]\n') - - def depart_meta(self, node): - self.body.append('[depart_meta]\n') - - def visit_note(self, node): - self.visit_admonition(node, 'note') - - def depart_note(self, node): - self.depart_admonition() - - - def visit_option(self, node): - if self.context[-1]: - # this is not the first option - self.body.append(', ') - - def depart_option(self, node): - # flag tha the first option is done. - self.context[-1] += 1 - - def visit_option_argument(self, node): - """The delimiter betweeen an option and its argument.""" - self.body.append(node.get('delimiter', ' ')) - - def depart_option_argument(self, node): - pass - - def visit_option_group(self, node): - self.body.append('\\item [') - self.context.append(0) - - def depart_option_group(self, node): - self.context.pop() # the flag - self.body.append('] ') - - def visit_option_list(self, node): - self.body.append('\\begin{description}\n') - - def depart_option_list(self, node): - self.body.append('\\end{description}\n') - - def visit_option_list_item(self, node): - pass - - def depart_option_list_item(self, node): - pass - - def re_repl_long(self, mo): - result = '\\longprogramopt{%s}' % mo.group(0)[2:] - return result - - def visit_option_string(self, node): - content = node.astext() - content = re.sub(PROGRAMOPT_RE, self.re_repl_long, content) - self.body.append(content) - raise nodes.SkipNode - - def depart_option_string(self, node): - pass - - - def visit_organization(self, node): - self.visit_docinfo_item(node, 'organization') - - def depart_organization(self, node): - self.depart_docinfo_item(node) - - def visit_paragraph(self, node): - if not self.topic_class == 'contents': - self.body.append('\n') - - def depart_paragraph(self, node): - self.body.append('\n') - - def visit_problematic(self, node): - self.body.append('{\\color{red}\\bfseries{}') - - def depart_problematic(self, node): - self.body.append('}') - - def visit_raw(self, node): - if node.has_key('format') and node['format'].lower() == 'latex': - self.body.append(node.astext()) - raise nodes.SkipNode - - def cleanHref(self, href): - href = href.replace('~', '\\~{}') - href = href.replace('#', '\\#{}') - return href - -## def visit_reference(self, node): -## self.pdebug('%% [(visit_reference) node: %s]\n' % str(node)) -## if node.has_key('refuri'): -## self.href = node['refuri'] -## elif node.has_key('refid'): -## self.href = '#' + node['refid'] -## elif node.has_key('refname'): -## self.href = '#' + self.document.nameids[node['refname']] -## self.href = self.cleanHref(self.href) -## if self.seealso: -## self.body.append('\\seeurl{%s}{' % self.href) -## else: -## self.body.append('\\ulink{') -## -## def depart_reference(self, node): -## if self.seealso: -## self.body.append('}') -## else: -## self.body.append('}{%s}' % self.href) - - def visit_reference(self, node): - #self.pdebug('%% [(visit_reference) node: %s]\n' % str(node)) - if self.seealso: - if node.has_key('refuri'): - href = node['refuri'] - href = self.cleanHref(href) - self.body.append('\\seeurl{%s}{' % href) - else: - if node.has_key('refuri'): - # External hyperlink - self.body.append('\\ulink{') - elif node.has_key('refid'): - # Internal hyperlink - href = node['refid'] - href = self.cleanHref(href) - self.body.append('\\ref{%s}' % href) - raise nodes.SkipNode - - def depart_reference(self, node): - if self.seealso: - self.body.append('}') - else: - if node.has_key('refuri'): - # External hyperlink - href = node['refuri'] - href = self.cleanHref(href) - self.body.append('}{%s}' % href) - elif node.has_key('refid'): - # Internal hyperlink - pass - - def visit_revision(self, node): - ## self.pdebug('%% [(visit_revision) node: "%s"]\n' % str(node)) - self.visit_docinfo_item(node, 'revision') - raise nodes.SkipNode - - def depart_revision(self, node): - self.depart_docinfo_item(node) - - def visit_section(self, node): - # If the document title came before the first (outer-most) - # section, then the first section is really the first section. - # If the document title is *in* the first section, then - # the first section is a container that has the document title. - # So, if the document title came before the first section, - # then alwasy increment the section_level. - # But, if the document title is *in* the first section, then - # increment the section_level only on the *second* and - # subsequent sections. - ## self.pdebug('%% [(visit_section) node: %s]\n' % repr(node)) - if self.title_before_section or self.seen_section: - self.section_level += 1 - self.seen_section = 1 - - def depart_section(self, node): - ## self.pdebug('%% [(depart_section) node: %s]\n' % repr(node)) - if self.title_before_section: - self.section_level -= 1 - - def visit_sidebar(self, node): - # BUG: this is just a hack to make sidebars render something - self.body.append('\\begin{center}\\begin{sffamily}\n') - self.body.append('\\fbox{\\colorbox[gray]{0.80}{\\parbox{\\admonitionwidth}{\n') - - def depart_sidebar(self, node): - self.body.append('}}}\n') # end parbox colorbox fbox - self.body.append('\\end{sffamily}\n\\end{center}\n'); - - - attribution_formats = {'dash': ('---', ''), - 'parentheses': ('(', ')'), - 'parens': ('(', ')'), - 'none': ('', '')} - - def visit_attribution(self, node): - prefix, suffix = self.attribution_formats[self.settings.attribution] - self.body.append('\n\\begin{flushright}\n') - self.body.append(prefix) - self.context.append(suffix) - - def depart_attribution(self, node): - self.body.append(self.context.pop() + '\n') - self.body.append('\\end{flushright}\n') - - def visit_status(self, node): - self.visit_docinfo_item(node, 'status') - - def depart_status(self, node): - self.depart_docinfo_item(node) - - def visit_strong(self, node): - self.body.append('\\strong{') - - def depart_strong(self, node): - self.body.append('}') - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_substitution_reference(self, node): - self.unimplemented_visit(node) - - def visit_subtitle(self, node): - self.title = self.title + \ - '\\\\\n\\large{%s}\n' % self.encode(node.astext()) - raise nodes.SkipNode - - def depart_subtitle(self, node): - pass - - def visit_system_message(self, node): - if node['level'] < self.document.reporter['writer'].report_level: - raise nodes.SkipNode - - - def depart_system_message(self, node): - self.body.append('\n') - - def visit_target(self, node): - #self.pdebug('%% [(visit_target) node: %s]\n' % str(node)) - pass -## if not (node.has_key('refuri') or node.has_key('refid') -## or node.has_key('refname')): -## self.body.append('\\hypertarget{%s}{' % node['name']) -## self.context.append('}') -## else: -## self.context.append('') - - def depart_target(self, node): - pass -## self.body.append(self.context.pop()) - - def visit_table(self, node): - self.tableSpec = TableSpec() - - def depart_table(self, node): - self.tablSpec = None - - def visit_tgroup(self, node): - columnCount = int(node.get('cols', 0)) - self.tableSpec.setColumnCount(columnCount) - if columnCount == 2: - self.body.append('\\begin{tableii}{l|l}{textrm}') - elif columnCount == 3: - self.body.append('\\begin{tableiii}{l|l|l}{textrm}') - elif columnCount == 4: - self.body.append('\\begin{tableiv}{l|l|l|l}{textrm}') - elif columnCount == 5: - self.body.append('\\begin{tablev}{l|l|l|l|l}{textrm}') - - def depart_tgroup(self, node): - if self.tableSpec.getColumnCount() == 2: - self.body.append('\n\\end{tableii}\n') - elif self.tableSpec.getColumnCount() == 3: - self.body.append('\n\\end{tableiii}\n') - elif self.tableSpec.getColumnCount() == 4: - self.body.append('\n\\end{tableiv}\n') - elif self.tableSpec.getColumnCount() == 5: - self.body.append('\n\\end{tablev}\n') - - def visit_thead(self, node): - self.tableSpec.setMode(TABLE_MODE_HEAD) - - def depart_thead(self, node): - self.tableSpec.setMode(TABLE_MODE_NONE) - - def visit_tbody(self, node): - self.tableSpec.setMode(TABLE_MODE_BODY) - - def depart_tbody(self, node): - self.tableSpec.setMode(TABLE_MODE_NONE) - - def visit_row(self, node): - if self.tableSpec.getMode() == TABLE_MODE_HEAD: - pass - elif self.tableSpec.getMode() == TABLE_MODE_BODY: - if self.tableSpec.getColumnCount() == 2: - self.body.append('\n\\lineii') - elif self.tableSpec.getColumnCount() == 3: - self.body.append('\n\\lineiii') - elif self.tableSpec.getColumnCount() == 4: - self.body.append('\n\\lineiv') - elif self.tableSpec.getColumnCount() == 5: - self.body.append('\n\\linev') - - def depart_row(self, node): - if self.tableSpec.getMode() == TABLE_MODE_HEAD: - pass - elif self.tableSpec.getMode() == TABLE_MODE_BODY: - pass - - def visit_entry(self, node): - if self.tableSpec.getMode() == TABLE_MODE_HEAD: - #self.body.append('%% [(visit_entry) text: +%s+]' % node.astext()) - self.body.append('{%s}' % node.astext().strip(' ')) - raise nodes.SkipNode - elif self.tableSpec.getMode() == TABLE_MODE_BODY: - #self.body.append('%% [(visit_entry) text: +%s+]' % node.astext()) - self.body.append('{%s}' % node.astext().strip(' ')) - raise nodes.SkipNode - - def depart_entry(self, node): - pass -## if self.tableSpec.getMode() == TABLE_MODE_HEAD: -## self.body.append('}') -## elif self.tableSpec.getMode() == TABLE_MODE_BODY: -## self.body.append('}') - - def visit_term(self, node): - self.body.append('\\item[') - - def depart_term(self, node): - # definition list term. - self.body.append(':]\n') - - def visit_tip(self, node): - self.visit_admonition(node, 'tip') - - def depart_tip(self, node): - self.depart_admonition() - -## def string_to_label(self, text): -## text = text.replace(' ', '-') -## text = text.replace('_', '-') -## return text - - def visit_title(self, node): - #self.pdebug('%% [(visit_title) section_level: %d node.astext: "%s"]\n' % \ - # (self.section_level, node.astext())) - #self.pdebug('%% [(visit_title) section_level: %d node.astext.encode: "%s"]\n' % \ - # (self.section_level, self.encode(node.astext()))) - if self.section_level == 0: - self.title_before_section = 1 - if self.seealso: - self.body.append('\\end{seealso}\n') - self.seealso = 0 - if node.astext().lower() == 'see also': - self.body.append('\\begin{seealso}\n') - self.seealso = 1 - raise nodes.SkipNode - else: - if self.section_level == 0: - # It's the document title before any section. - self.title = self.encode(node.astext()) - else: - # It's a title for a section in-side the document. - self.body.append('\n\n') - self.body.append('%' + '_' * 75) - self.body.append('\n\n') - s1 = self.encode(node.astext()) - # Remove the non-breaking space character. - # Not needed. Using output-encoding=latin-1 fixes this. - #s1 = s1.replace(u'\xa0', ' ') - s2 = nodes.make_id(node.astext()) - - #ipshell('(visit_title) Entering ipshell.\nHit Ctrl-D to exit ipshell.') - - if (self.section_level == 1): - self.body.append('\\section{%s\\label{%s}}\n' % (s1, s2)) - #self.body.append( - # '\\section{\htmladdnormallink[%s]{%s}{}}\n' % \ - # (s2, s1)) - elif (self.section_level == 2): - self.body.append('\\subsection{%s\\label{%s}}\n' % (s1, s2)) - elif (self.section_level == 3): - self.body.append('\\subsubsection{%s\\label{%s}}\n' % (s1, s2)) - elif (self.section_level == 4): - self.body.append('\\paragraph{%s\\label{%s}}\n' % (s1, s2)) - else: - self.body.append('\\subparagraph{%s\\label{%s}}\n' % (s1, s2)) - raise nodes.SkipNode - - def depart_title(self, node): - pass - - def visit_topic(self, node): - topic_class = node.get('class') - if topic_class == 'abstract': - self.docinfo['abstract'] = node.astext()[9:] - raise nodes.SkipNode - else: - raise nodes.SkipNode - - def depart_topic(self, node): - pass - - def visit_rubric(self, node): - self.body.append('% [(visit_rubric)]\n') - - def depart_rubric(self, node): - self.body.append('% [(depart_rubric)]\n') - - def visit_transition(self, node): - self.body.append('\n\n') - self.body.append('%' + '_' * 75) - self.body.append('\n\\hrule{}\n\n') - - def depart_transition(self, node): - pass - - def visit_version(self, node): - self.visit_docinfo_item(node, 'version') - - def depart_version(self, node): - self.depart_docinfo_item(node) - - def visit_warning(self, node): - self.visit_admonition(node, 'warning') - - def depart_warning(self, node): - self.depart_admonition() - - def unimplemented_visit(self, node): - raise NotImplementedError('visiting unimplemented node type: %s' - % node.__class__.__name__) - diff --git a/sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py b/sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py deleted file mode 100644 index e40300984..000000000 --- a/sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py +++ /dev/null @@ -1,698 +0,0 @@ -# Authors: David Goodger; Garth Kidd -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Exports the following: - -:Modules: - - `statemachine` is 'docutils.statemachine' - - `nodes` is 'docutils.nodes' - - `urischemes` is 'docutils.urischemes' - - `utils` is 'docutils.utils' - - `transforms` is 'docutils.transforms' - - `states` is 'docutils.parsers.rst.states' - - `tableparser` is 'docutils.parsers.rst.tableparser' - -:Classes: - - `CustomTestSuite` - - `CustomTestCase` - - `TransformTestSuite` - - `TransformTestCase` - - `ParserTestSuite` - - `ParserTestCase` - - `PEPParserTestSuite` - - `PEPParserTestCase` - - `GridTableParserTestSuite` - - `GridTableParserTestCase` - - `SimpleTableParserTestSuite` - - `SimpleTableParserTestCase` - - 'LatexPublishTestSuite' - - 'LatexPublishTestCase' - - 'PythonLatexPublishTestSuite' - - 'PythonLatexPublishTestCase' - - `DevNull` (output sink) -""" -__docformat__ = 'reStructuredText' - -import sys -import os -import unittest -import difflib -import inspect -from pprint import pformat -from types import UnicodeType -import package_unittest -import docutils -import docutils.core -from docutils import frontend, nodes, statemachine, urischemes, utils -from docutils.transforms import universal -from docutils.parsers import rst -from docutils.parsers.rst import states, tableparser, directives, languages -from docutils.readers import standalone, pep, python -from docutils.statemachine import StringList, string2lines - -try: - from docutils.readers.python import moduleparser -except: - moduleparser = None - -try: - import mypdb as pdb -except: - import pdb - - -# Hack to make repr(StringList) look like repr(list): -StringList.__repr__ = StringList.__str__ - - -class DevNull: - - """Output sink.""" - - def write(self, string): - pass - - -class CustomTestSuite(unittest.TestSuite): - - """ - A collection of custom TestCases. - - """ - - id = '' - """Identifier for the TestSuite. Prepended to the - TestCase identifiers to make identification easier.""" - - next_test_case_id = 0 - """The next identifier to use for non-identified test cases.""" - - def __init__(self, tests=(), id=None): - """ - Initialize the CustomTestSuite. - - Arguments: - - id -- identifier for the suite, prepended to test cases. - """ - unittest.TestSuite.__init__(self, tests) - if id is None: - mypath = os.path.abspath( - sys.modules[CustomTestSuite.__module__].__file__) - outerframes = inspect.getouterframes(inspect.currentframe()) - for outerframe in outerframes[1:]: - if outerframe[3] != '__init__': - callerpath = outerframe[1] - if callerpath is None: - # It happens sometimes. Why is a mystery. - callerpath = os.getcwd() - callerpath = os.path.abspath(callerpath) - break - mydir, myname = os.path.split(mypath) - if not mydir: - mydir = os.curdir - if callerpath.startswith(mydir): - self.id = callerpath[len(mydir) + 1:] # caller's module - else: - self.id = callerpath - else: - self.id = id - - def addTestCase(self, test_case_class, method_name, input, expected, - id=None, run_in_debugger=0, short_description=None, - **kwargs): - """ - Create a custom TestCase in the CustomTestSuite. - Also return it, just in case. - - Arguments: - - test_case_class -- - method_name -- - input -- input to the parser. - expected -- expected output from the parser. - id -- unique test identifier, used by the test framework. - run_in_debugger -- if true, run this test under the pdb debugger. - short_description -- override to default test description. - """ - if id is None: # generate id if required - id = self.next_test_case_id - self.next_test_case_id += 1 - # test identifier will become suiteid.testid - tcid = '%s: %s' % (self.id, id) - # generate and add test case - tc = test_case_class(method_name, input, expected, tcid, - run_in_debugger=run_in_debugger, - short_description=short_description, - **kwargs) - self.addTest(tc) - return tc - - -class CustomTestCase(unittest.TestCase): - - compare = difflib.Differ().compare - """Comparison method shared by all subclasses.""" - - def __init__(self, method_name, input, expected, id, - run_in_debugger=0, short_description=None): - """ - Initialise the CustomTestCase. - - Arguments: - - method_name -- name of test method to run. - input -- input to the parser. - expected -- expected output from the parser. - id -- unique test identifier, used by the test framework. - run_in_debugger -- if true, run this test under the pdb debugger. - short_description -- override to default test description. - """ - self.id = id - self.input = input - self.expected = expected - self.run_in_debugger = run_in_debugger - # Ring your mother. - unittest.TestCase.__init__(self, method_name) - - def __str__(self): - """ - Return string conversion. Overridden to give test id, in addition to - method name. - """ - return '%s; %s' % (self.id, unittest.TestCase.__str__(self)) - - def __repr__(self): - return "<%s %s>" % (self.id, unittest.TestCase.__repr__(self)) - - def compare_output(self, input, output, expected): - """`input`, `output`, and `expected` should all be strings.""" - if type(input) == UnicodeType: - input = input.encode('raw_unicode_escape') - if type(output) == UnicodeType: - output = output.encode('raw_unicode_escape') - if type(expected) == UnicodeType: - expected = expected.encode('raw_unicode_escape') - try: - self.assertEquals('\n' + output, '\n' + expected) - except AssertionError: - print >>sys.stderr, '\n%s\ninput:' % (self,) - print >>sys.stderr, input - print >>sys.stderr, '-: expected\n+: output' - print >>sys.stderr, ''.join(self.compare(expected.splitlines(1), - output.splitlines(1))) - raise - - def skip_test(self): - print >>sys.stderr, '%s: Test skipped' % self - - -class TransformTestSuite(CustomTestSuite): - - """ - A collection of TransformTestCases. - - A TransformTestSuite instance manufactures TransformTestCases, - keeps track of them, and provides a shared test fixture (a-la - setUp and tearDown). - """ - - def __init__(self, parser): - self.parser = parser - """Parser shared by all test cases.""" - - CustomTestSuite.__init__(self) - - def generateTests(self, dict, dictname='totest', - testmethod='test_transforms'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type's name) maps to a list of transform - classes and list of tests. Each test is a list: input, expected - output, optional modifier. The optional third entry, a behavior - modifier, can be 0 (temporarily disable this test) or 1 (run this test - under the pdb debugger). Tests should be self-documenting and not - require external comments. - """ - for name, (transforms, cases) in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - TransformTestCase, testmethod, - transforms=transforms, parser=self.parser, - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class TransformTestCase(CustomTestCase): - - """ - Output checker for the transform. - - Should probably be called TransformOutputChecker, but I can deal with - that later when/if someone comes up with a category of transform test - cases that have nothing to do with the input and output of the transform. - """ - - option_parser = frontend.OptionParser(components=(rst.Parser,)) - settings = option_parser.get_default_values() - settings.report_level = 1 - settings.halt_level = 5 - settings.debug = package_unittest.debug - settings.warning_stream = DevNull() - - def __init__(self, *args, **kwargs): - self.transforms = kwargs['transforms'] - """List of transforms to perform for this test case.""" - - self.parser = kwargs['parser'] - """Input parser for this test case.""" - - del kwargs['transforms'], kwargs['parser'] # only wanted here - CustomTestCase.__init__(self, *args, **kwargs) - - def supports(self, format): - return 1 - - def test_transforms(self): - if self.run_in_debugger: - pdb.set_trace() - document = utils.new_document('test data', self.settings) - self.parser.parse(self.input, document) - # Don't do a ``populate_from_components()`` because that would - # enable the Transformer's default transforms. - document.transformer.add_transforms(self.transforms) - document.transformer.add_transform(universal.TestMessages) - document.transformer.components['writer'] = self - document.transformer.apply_transforms() - output = document.pformat() - self.compare_output(self.input, output, self.expected) - - def test_transforms_verbosely(self): - if self.run_in_debugger: - pdb.set_trace() - print '\n', self.id - print '-' * 70 - print self.input - document = utils.new_document('test data', self.settings) - self.parser.parse(self.input, document) - print '-' * 70 - print document.pformat() - for transformClass in self.transforms: - transformClass(document).apply() - output = document.pformat() - print '-' * 70 - print output - self.compare_output(self.input, output, self.expected) - - -class ParserTestCase(CustomTestCase): - - """ - Output checker for the parser. - - Should probably be called ParserOutputChecker, but I can deal with - that later when/if someone comes up with a category of parser test - cases that have nothing to do with the input and output of the parser. - """ - - parser = rst.Parser() - """Parser shared by all ParserTestCases.""" - - option_parser = frontend.OptionParser(components=(parser,)) - settings = option_parser.get_default_values() - settings.report_level = 5 - settings.halt_level = 5 - settings.debug = package_unittest.debug - - def test_parser(self): - if self.run_in_debugger: - pdb.set_trace() - document = utils.new_document('test data', self.settings) - self.parser.parse(self.input, document) - output = document.pformat() - self.compare_output(self.input, output, self.expected) - - -class ParserTestSuite(CustomTestSuite): - - """ - A collection of ParserTestCases. - - A ParserTestSuite instance manufactures ParserTestCases, - keeps track of them, and provides a shared test fixture (a-la - setUp and tearDown). - """ - - test_case_class = ParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: input, expected output, optional modifier. The - optional third entry, a behavior modifier, can be 0 (temporarily - disable this test) or 1 (run this test under the pdb debugger). Tests - should be self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - self.test_case_class, 'test_parser', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PEPParserTestCase(ParserTestCase): - - """PEP-specific parser test case.""" - - parser = rst.Parser(rfc2822=1, inliner=pep.Inliner()) - """Parser shared by all PEPParserTestCases.""" - - option_parser = frontend.OptionParser(components=(parser, pep.Reader)) - settings = option_parser.get_default_values() - settings.report_level = 5 - settings.halt_level = 5 - settings.debug = package_unittest.debug - - -class PEPParserTestSuite(ParserTestSuite): - - """A collection of PEPParserTestCases.""" - - test_case_class = PEPParserTestCase - - -class GridTableParserTestCase(CustomTestCase): - - parser = tableparser.GridTableParser() - - def test_parse_table(self): - self.parser.setup(StringList(string2lines(self.input), 'test data')) - try: - self.parser.find_head_body_sep() - self.parser.parse_table() - output = self.parser.cells - except Exception, details: - output = '%s: %s' % (details.__class__.__name__, details) - self.compare_output(self.input, pformat(output) + '\n', - pformat(self.expected) + '\n') - - def test_parse(self): - try: - output = self.parser.parse(StringList(string2lines(self.input), - 'test data')) - except Exception, details: - output = '%s: %s' % (details.__class__.__name__, details) - self.compare_output(self.input, pformat(output) + '\n', - pformat(self.expected) + '\n') - - -class GridTableParserTestSuite(CustomTestSuite): - - """ - A collection of GridTableParserTestCases. - - A GridTableParserTestSuite instance manufactures GridTableParserTestCases, - keeps track of them, and provides a shared test fixture (a-la setUp and - tearDown). - """ - - test_case_class = GridTableParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: an input table, expected output from parse_table(), - expected output from parse(), optional modifier. The optional fourth - entry, a behavior modifier, can be 0 (temporarily disable this test) - or 1 (run this test under the pdb debugger). Tests should be - self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case) == 4: - if case[-1]: - run_in_debugger = 1 - else: - continue - self.addTestCase(self.test_case_class, 'test_parse_table', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - self.addTestCase(self.test_case_class, 'test_parse', - input=case[0], expected=case[2], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class SimpleTableParserTestCase(GridTableParserTestCase): - - parser = tableparser.SimpleTableParser() - - -class SimpleTableParserTestSuite(CustomTestSuite): - - """ - A collection of SimpleTableParserTestCases. - """ - - test_case_class = SimpleTableParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: an input table, expected output from parse(), optional - modifier. The optional third entry, a behavior modifier, can be 0 - (temporarily disable this test) or 1 (run this test under the pdb - debugger). Tests should be self-documenting and not require external - comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case) == 3: - if case[-1]: - run_in_debugger = 1 - else: - continue - self.addTestCase(self.test_case_class, 'test_parse', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PythonModuleParserTestCase(CustomTestCase): - - def test_parser(self): - if self.run_in_debugger: - pdb.set_trace() - module = moduleparser.parse_module(self.input, 'test data') - output = str(module) - self.compare_output(self.input, output, self.expected) - - def test_token_parser_rhs(self): - if self.run_in_debugger: - pdb.set_trace() - tr = moduleparser.TokenParser(self.input) - output = tr.rhs(1) - self.compare_output(self.input, output, self.expected) - - -class PythonModuleParserTestSuite(CustomTestSuite): - - """ - A collection of PythonModuleParserTestCase. - """ - - if moduleparser is None: - PythonModuleParserTestCase.test_parser = CustomTestCase.skip_test - PythonModuleParserTestCase.test_token_parser_rhs = \ - CustomTestCase.skip_test - - def generateTests(self, dict, dictname='totest', - testmethod='test_parser'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type's name) maps to a list of tests. Each - test is a list: input, expected output, optional modifier. The - optional third entry, a behavior modifier, can be 0 (temporarily - disable this test) or 1 (run this test under the pdb debugger). Tests - should be self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - PythonModuleParserTestCase, testmethod, - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -# @@@ These should be generalized to WriterPublishTestCase/Suite or -# just PublishTestCase/Suite, as per TransformTestCase/Suite. -class LatexPublishTestCase(CustomTestCase, docutils.SettingsSpec): - - """ - Test case for publish. - """ - - settings_default_overrides = {'_disable_config': 1} - - def test_publish(self): - if self.run_in_debugger: - pdb.set_trace() - output = docutils.core.publish_string( - source=self.input, - reader_name='standalone', - parser_name='restructuredtext', - writer_name='latex', - settings_spec=self) - self.compare_output(self.input, output, self.expected) - - -class LatexPublishTestSuite(CustomTestSuite): - - def __init__(self): - CustomTestSuite.__init__(self) - - def generateTests(self, dict, dictname='totest'): - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - LatexPublishTestCase, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PythonLatexPublishTestCase(CustomTestCase, docutils.SettingsSpec): - - """ - Test case for publish. - """ - - settings_default_overrides = {'_disable_config': 1} - - def test_publish(self): - if self.run_in_debugger: - pdb.set_trace() - output = docutils.core.publish_string( - source=self.input, - reader_name='standalone', - parser_name='restructuredtext', - writer_name='python_latex', - settings_spec=self) - self.compare_output(self.input, output, self.expected) - - def compare_output(self, input, output, expected): - """`input`, `output`, and `expected` should all be strings.""" - if type(input) == UnicodeType: - input = input.encode('raw_unicode_escape') - if type(output) == UnicodeType: - output = output.encode('raw_unicode_escape') - if type(expected) == UnicodeType: - expected = expected.encode('raw_unicode_escape') - # Remove "generated on" lines. - output = self.remove_lines(output, ('generated on --',)) - expected = self.remove_lines(expected, ('generated on --',)) - try: - self.assertEquals('\n' + output, '\n' + expected) - except AssertionError: - print >>sys.stderr, '\n%s\ninput:' % (self,) - print >>sys.stderr, input - print >>sys.stderr, '-: expected\n+: output' - print >>sys.stderr, ''.join(self.compare(expected.splitlines(1), - output.splitlines(1))) - raise - - def remove_lines(self, inStr, targetList): - inLines = inStr.splitlines() - outLines = [] - for line in inLines: - remove = False - for target in targetList: - if line.find(target) > -1: - remove = True - break - if not remove: - outLines.append(line) - outStr = '\n'.join(outLines) - return outStr - -class PythonLatexPublishTestSuite(CustomTestSuite): - - def __init__(self): - CustomTestSuite.__init__(self) - - def generateTests(self, dict, dictname='totest'): - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - PythonLatexPublishTestCase, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -def exception_data(code): - """ - Execute `code` and return the resulting exception, the exception arguments, - and the formatted exception string. - """ - try: - exec(code) - except Exception, detail: - return (detail, detail.args, - '%s: %s' % (detail.__class__.__name__, detail)) diff --git a/sandbox/dkuhlman/docutils/test/README.test_python_latex b/sandbox/dkuhlman/docutils/test/README.test_python_latex deleted file mode 100644 index a8321744e..000000000 --- a/sandbox/dkuhlman/docutils/test/README.test_python_latex +++ /dev/null @@ -1,36 +0,0 @@ - -============================================= -Notes on Unit Test Additions for Python LaTeX -============================================= - - -DocutilsTestSupport.py -====================== - -Added two classes (PythonLatexPublishTestCase and -PythonLatexPublishTestSuite) that drive the tests. These classes -were modelled on classes LatexPublishTestCase and -LatexPublishTestSuite respectively. - -Note that class PythonLatexPublishTestCase overrides method -compare_output and adds method remove_lines. These methods remove -the "generated on" lines from both input and output because the -date will always differ. - -See file DocutilsTestSupport.patch - - -test_writers/test_python_latex.py -================================= - -Contains the tests. - - -test_writers/Data/* -=================== - -Contains reST source documents (*.txt) and generated LaTeX -documents (*.tex) that were used in the input and output strings -in test_python_latex.py. - - diff --git a/sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py b/sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py deleted file mode 100644 index 7aa5528ce..000000000 --- a/sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py +++ /dev/null @@ -1,490 +0,0 @@ -#! /usr/bin/env python - -# Author: Dave Kuhlman -# Contact: dkuhlman@rexx.com -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for python_latex writer. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.PythonLatexPublishTestSuite() - s.generateTests(totest) - return s - - -rest_head = """\ - -========================== -Unit Test for Python LaTeX -========================== - - -:author: Dave Kuhlman -:address: dkuhlman@rexx.com \\\\ - http://www.rexx.com/~dkuhlman - -:revision: 1.0a -:date: Aug. 4, 2003 - -:copyright: Copyright (c) 2003 Dave Kuhlman. - [an Open Source copyright] - -:abstract: This document contains input for unit tests for the - Python LaTeX writer for Docutils. - -.. sectnum:: :depth: 2 - -.. contents:: - - -""" - -latex_head = r"""\documentclass{howto} - -% generator -- Docutils: http://docutils.sourceforge.net/ -% writer -- documenting_python -% generated on -- Wed Aug 13 16:08:04 2003 - -\usepackage{html} -\title{Unit Test for Python LaTeX} -\release{1.0a} -\date{Aug. 4, 2003} -\author{Dave Kuhlman} -\authoraddress{dkuhlman@rexx.com \ -http://www.rexx.com/\~{}dkuhlman} -\begin{document} -\maketitle -\ifhtml -\chapter*{Front Matter\label{front}} -\fi - -Copyright (c) 2003 Dave Kuhlman. -[an Open Source copyright] -\begin{abstract} -\noindent - -This document contains input for unit tests for the -Python LaTeX writer for Docutils. -\end{abstract} -\tableofcontents - -""" - -totest = {} - -totest['section_headers'] = [ -# input -[rest_head + r""" -Section #1 -========== - -Content for section #1. - -Subsection #1-1 ---------------- - -Content for sub-section #1-1. - -Subsection #1-2 ---------------- - -Content for sub-section #1-2. - -Section #2 -========== - -Content for section #2. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Section {\#}1\label{section-1}} - -Content for section {\#}1. - - -%___________________________________________________________________________ - -\subsection{1.1 Subsection {\#}1-1\label{subsection-1-1}} - -Content for sub-section {\#}1-1. - - -%___________________________________________________________________________ - -\subsection{1.2 Subsection {\#}1-2\label{subsection-1-2}} - -Content for sub-section {\#}1-2. - - -%___________________________________________________________________________ - -\section{2 Section {\#}2\label{section-2}} - -Content for section {\#}2. - -\end{document} -"""], -] - -# ============================================================== - -totest['enumerated_lists'] = [ -# input -[rest_head + r""" -Enumerated List Test Section -============================ - -Here is an enumerated list: - -1. This is an item. - -2. This is an item. - -3. This is an item. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Enumerated List Test Section\label{enumerated-list-test-section}} - -Here is an enumerated list: -\begin{enumerate} -\item -This is an item. - -\item -This is an item. - -\item -This is an item. - -\end{enumerate} - -\end{document} -"""], -] - - -# ============================================================== - -totest['itemized_lists'] = [ -# input -[rest_head + r""" -Itemized List Test Section -========================== - -Here is an itemized list: - -- This is an item. - -- This is an item. - -- This is an item. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Itemized List Test Section\label{itemized-list-test-section}} - -Here is an itemized list: -\begin{itemize} -\item -This is an item. - -\item -This is an item. - -\item -This is an item. - -\end{itemize} - -\end{document} -"""], -] - -# ============================================================== - -totest['links'] = [ -# input -[rest_head + r""" -Section #1 -========== - -Content for section #1. - -Subsection #1-1 ---------------- - -Content for sub-section #1-1. - -Subsection #1-2 ---------------- - -Content for sub-section #1-2. - -Section #2 -========== - -Content for section #2. - -Links Test Section -================== - -Here is a link to the section which is the target of this -internal link `Subsection #1-1`_. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Section {\#}1\label{section-1}} - -Content for section {\#}1. - - -%___________________________________________________________________________ - -\subsection{1.1 Subsection {\#}1-1\label{subsection-1-1}} - -Content for sub-section {\#}1-1. - - -%___________________________________________________________________________ - -\subsection{1.2 Subsection {\#}1-2\label{subsection-1-2}} - -Content for sub-section {\#}1-2. - - -%___________________________________________________________________________ - -\section{2 Section {\#}2\label{section-2}} - -Content for section {\#}2. - - -%___________________________________________________________________________ - -\section{3 Links Test Section\label{links-test-section}} - -Here is a link to the section which is the target of this -internal link \ref{subsection-1-1}. - -\end{document} -"""], -] - -# ============================================================== - -totest['seealso'] = [ -# input -[rest_head + r""" -See Also -======== - -`Docutils: Python Documentation Utilities`_ - -.. _`Docutils: Python Documentation Utilities`: - http://docutils.sourceforge.net/ - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 See Also\label{see-also}} - -\ulink{Docutils: Python Documentation Utilities}{http://docutils.sourceforge.net/} - -\end{document} -"""], -] - - -# ============================================================== - -totest['emphasis'] = [ -# input -[rest_head + r""" -Section #1 -========== - -This section contains *some emphaized text*. - -It **also has some bold text**. - -And ``this is sample text``, or, as it is known in reStructured -Text, an in-line literal. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Section {\#}1\label{section-1}} - -This section contains \emph{some emphaized text}. - -It \strong{also has some bold text}. - -And \samp{this is sample text}, or, as it is known in reStructured -Text, an in-line literal. - -\end{document} -"""], -] - - -# ============================================================== - -totest['blockquote'] = [ -# input -[rest_head + r""" -Block Quote Test -================ - -This section contains a paragraph which is followed by a block -quote. The block quote is a simple paragraph that is indented. - - This is the block quoted paragraph. It has several sentences. - These sentences have empty content because they are only a - test. This is a test. This is a test. This is a test. This - is a test. This is a test. This is a test. - - -Python Iteractive Session Test -============================== - -This section has a Python interactive session. It is a test. -Here is the example session. - ->>> import sys ->>> print sys.version -2.3 (#1, Jul 31 2003, 15:26:15) -[GCC 3.2.3 20030415 (Debian prerelease)] ->>> a = [11,22,33] ->>> for x in a: -... print x -... -11 -22 -33 - - -Literal Block Test -================== - -This section has a literal block. In Python LaTeX it will be -formatted in a verbatim environment:: - - def remove_lines(self, inStr, targetList): - inLines = inStr.splitlines() - outLines = [] - for line in inLines: - remove = False - for target in targetList: - if line.find(target) > -1: - remove = True - if not remove: - outLines.append(line) - outStr = '\n'.join(outLines) - return outStr - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Block Quote Test\label{block-quote-test}} - -This section contains a paragraph which is followed by a block -quote. The block quote is a simple paragraph that is indented. -\begin{quote} - -This is the block quoted paragraph. It has several sentences. -These sentences have empty content because they are only a -test. This is a test. This is a test. This is a test. This -is a test. This is a test. This is a test. -\end{quote} - - -%___________________________________________________________________________ - -\section{2 Python Iteractive Session Test\label{python-iteractive-session-test}} - -This section has a Python interactive session. It is a test. -Here is the example session. -\begin{verbatim} ->>> import sys ->>> print sys.version -2.3 (#1, Jul 31 2003, 15:26:15) -[GCC 3.2.3 20030415 (Debian prerelease)] ->>> a = [11,22,33] ->>> for x in a: -... print x -... -11 -22 -33 -\end{verbatim} - - -%___________________________________________________________________________ - -\section{3 Literal Block Test\label{literal-block-test}} - -This section has a literal block. In Python LaTeX it will be -formatted in a verbatim environment: - -\begin{verbatim} -def remove_lines(self, inStr, targetList): - inLines = inStr.splitlines() - outLines = [] - for line in inLines: - remove = False - for target in targetList: - if line.find(target) > -1: - remove = True - if not remove: - outLines.append(line) - outStr = '\n'.join(outLines) - return outStr -\end{verbatim} - -\end{document} -"""], -] - - -# ============================================================== - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') - - - - - diff --git a/sandbox/dkuhlman/docutils/tools/python_latex.py b/sandbox/dkuhlman/docutils/tools/python_latex.py deleted file mode 100755 index 245f7aafa..000000000 --- a/sandbox/dkuhlman/docutils/tools/python_latex.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python - -""" -:Author: Dave Kuhlman -:Contact: dkuhlman@rexx.com -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. - -A minimal front end to the Docutils Publisher, producing LaTeX -that conforms to Documenting Python -(http://www.python.org/dev/doc/devel/doc/doc.html). -""" - -#import locale -#locale.setlocale(locale.LC_ALL, '') - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates LaTeX for "Documenting Python" documents ' - 'from standalone reStructuredText ' - 'sources. ' + default_description) - -publish_cmdline(writer_name='python_latex', description=description) |