bee_python 0.0.1

data/tools/epydoc/docwriter/latex.py

@@ -0,0 +1,1187 @@
+#
+# epydoc.py: epydoc LaTeX output generator
+# Edward Loper
+#
+# Created [01/30/01 05:18 PM]
+# $Id: latex.py,v 1.1 2009/11/26 13:20:47 casa Exp $
+#
+
+"""
+The LaTeX output generator for epydoc.  The main interface provided by
+this module is the L{LatexWriter} class.
+
+@todo: Inheritance=listed
+"""
+__docformat__ = 'epytext en'
+
+import os.path, sys, time, re, textwrap, codecs
+
+from epydoc.apidoc import *
+from epydoc.compat import *
+import epydoc
+from epydoc import log
+from epydoc import markup
+from epydoc.util import plaintext_to_latex
+import epydoc.markup
+
+class LatexWriter:
+    PREAMBLE = [
+        "\\documentclass{article}",
+        "\\usepackage{alltt, parskip, fancyhdr, boxedminipage}",
+        "\\usepackage{makeidx, multirow, longtable, tocbibind, amssymb}",
+        "\\usepackage{fullpage}",
+        "\\usepackage[usenames]{color}",
+        # Fix the heading position -- without this, the headings generated
+        # by the fancyheadings package sometimes overlap the text.
+        "\\setlength{\\headheight}{16pt}",
+        "\\setlength{\\headsep}{24pt}",
+        "\\setlength{\\topmargin}{-\\headsep}",
+        # By default, do not indent paragraphs.
+        "\\setlength{\\parindent}{0ex}",
+        "\\setlength{\\parskip}{2ex}",
+        # Double the standard size boxedminipage outlines.
+        "\\setlength{\\fboxrule}{2\\fboxrule}",
+        # Create a 'base class' length named BCL for use in base trees.
+        "\\newlength{\\BCL} % base class length, for base trees.",
+        # Display the section & subsection names in a header.
+        "\\pagestyle{fancy}",
+        "\\renewcommand{\\sectionmark}[1]{\\markboth{#1}{}}",
+        "\\renewcommand{\\subsectionmark}[1]{\\markright{#1}}",
+        # Colorization for python source code
+        "\\definecolor{py@keywordcolour}{rgb}{1,0.45882,0}",
+        "\\definecolor{py@stringcolour}{rgb}{0,0.666666,0}",
+        "\\definecolor{py@commentcolour}{rgb}{1,0,0}",
+        "\\definecolor{py@ps1colour}{rgb}{0.60784,0,0}",
+        "\\definecolor{py@ps2colour}{rgb}{0.60784,0,1}",
+        "\\definecolor{py@inputcolour}{rgb}{0,0,0}",
+        "\\definecolor{py@outputcolour}{rgb}{0,0,1}",
+        "\\definecolor{py@exceptcolour}{rgb}{1,0,0}",
+        "\\definecolor{py@defnamecolour}{rgb}{1,0.5,0.5}",
+        "\\definecolor{py@builtincolour}{rgb}{0.58039,0,0.58039}",
+        "\\definecolor{py@identifiercolour}{rgb}{0,0,0}",
+        "\\definecolor{py@linenumcolour}{rgb}{0.4,0.4,0.4}",
+        "\\definecolor{py@inputcolour}{rgb}{0,0,0}",
+        "% Prompt",
+        "\\newcommand{\\pysrcprompt}[1]{\\textcolor{py@ps1colour}"
+            "{\\small\\textbf{#1}}}",
+        "\\newcommand{\\pysrcmore}[1]{\\textcolor{py@ps2colour}"
+            "{\\small\\textbf{#1}}}",
+        "% Source code",
+        "\\newcommand{\\pysrckeyword}[1]{\\textcolor{py@keywordcolour}"
+            "{\\small\\textbf{#1}}}",
+        "\\newcommand{\\pysrcbuiltin}[1]{\\textcolor{py@builtincolour}"
+            "{\\small\\textbf{#1}}}",
+        "\\newcommand{\\pysrcstring}[1]{\\textcolor{py@stringcolour}"
+            "{\\small\\textbf{#1}}}",
+        "\\newcommand{\\pysrcdefname}[1]{\\textcolor{py@defnamecolour}"
+            "{\\small\\textbf{#1}}}",
+        "\\newcommand{\\pysrcother}[1]{\\small\\textbf{#1}}",
+        "% Comments",
+        "\\newcommand{\\pysrccomment}[1]{\\textcolor{py@commentcolour}"
+            "{\\small\\textbf{#1}}}",
+        "% Output",
+        "\\newcommand{\\pysrcoutput}[1]{\\textcolor{py@outputcolour}"
+            "{\\small\\textbf{#1}}}",
+        "% Exceptions",
+        "\\newcommand{\\pysrcexcept}[1]{\\textcolor{py@exceptcolour}"
+            "{\\small\\textbf{#1}}}",
+        # Size of the function description boxes.
+        "\\newlength{\\funcindent}",
+        "\\newlength{\\funcwidth}",
+        "\\setlength{\\funcindent}{1cm}",
+        "\\setlength{\\funcwidth}{\\textwidth}",
+        "\\addtolength{\\funcwidth}{-2\\funcindent}",
+        # Size of the var description tables.
+        "\\newlength{\\varindent}",
+        "\\newlength{\\varnamewidth}",
+        "\\newlength{\\vardescrwidth}",
+        "\\newlength{\\varwidth}",
+        "\\setlength{\\varindent}{1cm}",
+        "\\setlength{\\varnamewidth}{.3\\textwidth}",
+        "\\setlength{\\varwidth}{\\textwidth}",
+        "\\addtolength{\\varwidth}{-4\\tabcolsep}",
+        "\\addtolength{\\varwidth}{-3\\arrayrulewidth}",
+        "\\addtolength{\\varwidth}{-2\\varindent}",
+        "\\setlength{\\vardescrwidth}{\\varwidth}",
+        "\\addtolength{\\vardescrwidth}{-\\varnamewidth}",
+        # Define new environment for displaying parameter lists.
+        textwrap.dedent("""\
+        \\newenvironment{Ventry}[1]%
+         {\\begin{list}{}{%
+           \\renewcommand{\\makelabel}[1]{\\texttt{##1:}\\hfil}%
+           \\settowidth{\\labelwidth}{\\texttt{#1:}}%
+           \\setlength{\\leftmargin}{\\labelsep}%
+           \\addtolength{\\leftmargin}{\\labelwidth}}}%
+         {\\end{list}}"""),
+        ]
+
+    HRULE = '\\rule{\\textwidth}{0.5\\fboxrule}\n\n'
+
+    SECTIONS = ['\\part{%s}', '\\chapter{%s}', '\\section{%s}',
+                '\\subsection{%s}', '\\subsubsection{%s}',
+                '\\textbf{%s}']
+
+    STAR_SECTIONS = ['\\part*{%s}', '\\chapter*{%s}', '\\section*{%s}',
+                     '\\subsection*{%s}', '\\subsubsection*{%s}',
+                     '\\textbf{%s}']
+
+    def __init__(self, docindex, **kwargs):
+        self.docindex = docindex
+        # Process keyword arguments
+        self._show_private = kwargs.get('private', 0)
+        self._prj_name = kwargs.get('prj_name', None) or 'API Documentation'
+        self._crossref = kwargs.get('crossref', 1)
+        self._index = kwargs.get('index', 1)
+        self._list_classes_separately=kwargs.get('list_classes_separately',0)
+        self._inheritance = kwargs.get('inheritance', 'listed')
+        self._exclude = kwargs.get('exclude', 1)
+        self._top_section = 2
+        self._index_functions = 1
+        self._hyperref = 1
+
+        #: The Python representation of the encoding.
+        #: Update L{latex_encodings} in case of mismatch between it and
+        #: the C{inputenc} LaTeX package.
+        self._encoding = kwargs.get('encoding', 'utf-8')
+
+        self.valdocs = valdocs = sorted(docindex.reachable_valdocs(
+            imports=False, packages=False, bases=False, submodules=False, 
+            subclasses=False, private=self._show_private))
+        self._num_files = self.num_files()
+        # For use with select_variables():
+        if self._show_private: self._public_filter = None
+        else: self._public_filter = True
+
+        self.class_list = [d for d in valdocs if isinstance(d, ClassDoc)]
+        """The list of L{ClassDoc}s for the documented classes."""
+        self.class_set = set(self.class_list)
+        """The set of L{ClassDoc}s for the documented classes."""
+        
+    def write(self, directory=None):
+        """
+        Write the API documentation for the entire project to the
+        given directory.
+
+        @type directory: C{string}
+        @param directory: The directory to which output should be
+            written.  If no directory is specified, output will be
+            written to the current directory.  If the directory does
+            not exist, it will be created.
+        @rtype: C{None}
+        @raise OSError: If C{directory} cannot be created,
+        @raise OSError: If any file cannot be created or written to.
+        """
+        # For progress reporting:
+        self._files_written = 0.
+        
+        # Set the default values for ValueDoc formatted representations.
+        orig_valdoc_defaults = (ValueDoc.SUMMARY_REPR_LINELEN,
+                                ValueDoc.REPR_LINELEN,
+                                ValueDoc.REPR_MAXLINES)
+        ValueDoc.SUMMARY_REPR_LINELEN = 60
+        ValueDoc.REPR_LINELEN = 52
+        ValueDoc.REPR_MAXLINES = 5
+
+        # Create destination directories, if necessary
+        if not directory: directory = os.curdir
+        self._mkdir(directory)
+        self._directory = directory
+        
+        # Write the top-level file.
+        self._write(self.write_topfile, directory, 'api.tex')
+
+        # Write the module & class files.
+        for val_doc in self.valdocs:
+            if isinstance(val_doc, ModuleDoc):
+                filename = '%s-module.tex' % val_doc.canonical_name
+                self._write(self.write_module, directory, filename, val_doc)
+            elif (isinstance(val_doc, ClassDoc) and 
+                  self._list_classes_separately):
+                filename = '%s-class.tex' % val_doc.canonical_name
+                self._write(self.write_class, directory, filename, val_doc)
+
+        # Restore defaults that we changed.
+        (ValueDoc.SUMMARY_REPR_LINELEN, ValueDoc.REPR_LINELEN,
+         ValueDoc.REPR_MAXLINES) = orig_valdoc_defaults
+        
+    def _write(self, write_func, directory, filename, *args):
+        # Display our progress.
+        self._files_written += 1
+        log.progress(self._files_written/self._num_files, filename)
+        
+        path = os.path.join(directory, filename)
+        if self._encoding == 'utf-8':
+            f = codecs.open(path, 'w', 'utf-8')
+            write_func(f.write, *args)
+            f.close()
+        else:
+            result = []
+            write_func(result.append, *args)
+            s = u''.join(result)
+            try:
+                s = s.encode(self._encoding)
+            except UnicodeError:
+                log.error("Output could not be represented with the "
+                          "given encoding (%r).  Unencodable characters "
+                          "will be displayed as '?'.  It is recommended "
+                          "that you use a different output encoding (utf-8, "
+                          "if it's supported by latex on your system)."
+                          % self._encoding)
+                s = s.encode(self._encoding, 'replace')
+            f = open(path, 'w')
+            f.write(s)
+            f.close()
+
+    def num_files(self):
+        """
+        @return: The number of files that this C{LatexFormatter} will
+            generate.
+        @rtype: C{int}
+        """
+        n = 1
+        for doc in self.valdocs:
+            if isinstance(doc, ModuleDoc): n += 1
+            if isinstance(doc, ClassDoc) and self._list_classes_separately:
+                n += 1
+        return n
+        
+    def _mkdir(self, directory):
+        """
+        If the given directory does not exist, then attempt to create it.
+        @rtype: C{None}
+        """
+        if not os.path.isdir(directory):
+            if os.path.exists(directory):
+                raise OSError('%r is not a directory' % directory)
+            os.mkdir(directory)
+            
+    #////////////////////////////////////////////////////////////
+    #{ Main Doc File
+    #////////////////////////////////////////////////////////////
+
+    def write_topfile(self, out):
+        self.write_header(out, 'Include File')
+        self.write_preamble(out)
+        out('\n\\begin{document}\n\n')
+        self.write_start_of(out, 'Header')
+
+        # Write the title.
+        self.write_start_of(out, 'Title')
+        out('\\title{%s}\n' % plaintext_to_latex(self._prj_name, 1))
+        out('\\author{API Documentation}\n')
+        out('\\maketitle\n')
+
+        # Add a table of contents.
+        self.write_start_of(out, 'Table of Contents')
+        out('\\addtolength{\\parskip}{-2ex}\n')
+        out('\\tableofcontents\n')
+        out('\\addtolength{\\parskip}{2ex}\n')
+
+        # Include documentation files.
+        self.write_start_of(out, 'Includes')
+        for val_doc in self.valdocs:
+            if isinstance(val_doc, ModuleDoc):
+                out('\\include{%s-module}\n' % val_doc.canonical_name)
+
+        # If we're listing classes separately, put them after all the
+        # modules.
+        if self._list_classes_separately:
+            for val_doc in self.valdocs:
+                if isinstance(val_doc, ClassDoc):
+                    out('\\include{%s-class}\n' % val_doc.canonical_name)
+
+        # Add the index, if requested.
+        if self._index:
+            self.write_start_of(out, 'Index')
+            out('\\printindex\n\n')
+
+        # Add the footer.
+        self.write_start_of(out, 'Footer')
+        out('\\end{document}\n\n')
+
+    def write_preamble(self, out):
+        out('\n'.join(self.PREAMBLE))
+        out('\n')
+        
+        # Set the encoding.
+        out('\\usepackage[%s]{inputenc}\n' % self.get_latex_encoding())
+
+        # If we're generating hyperrefs, add the appropriate packages.
+        if self._hyperref:
+            out('\\definecolor{UrlColor}{rgb}{0,0.08,0.45}\n')
+            out('\\usepackage[dvips, pagebackref, pdftitle={%s}, '
+                'pdfcreator={epydoc %s}, bookmarks=true, '
+                'bookmarksopen=false, pdfpagemode=UseOutlines, '
+                'colorlinks=true, linkcolor=black, anchorcolor=black, '
+                'citecolor=black, filecolor=black, menucolor=black, '
+                'pagecolor=black, urlcolor=UrlColor]{hyperref}\n' %
+                (self._prj_name or '', epydoc.__version__))
+            
+        # If we're generating an index, add it to the preamble.
+        if self._index:
+            out("\\makeindex\n")
+
+        # If restructuredtext was used, then we need to extend
+        # the prefix to include LatexTranslator.head_prefix.
+        if 'restructuredtext' in epydoc.markup.MARKUP_LANGUAGES_USED:
+            from epydoc.markup import restructuredtext
+            rst_head = restructuredtext.latex_head_prefix()
+            rst_head = ''.join(rst_head).split('\n')
+            for line in rst_head[1:]:
+                m = re.match(r'\\usepackage(\[.*?\])?{(.*?)}', line)
+                if m and m.group(2) in (
+                    'babel', 'hyperref', 'color', 'alltt', 'parskip',
+                    'fancyhdr', 'boxedminipage', 'makeidx',
+                    'multirow', 'longtable', 'tocbind', 'assymb',
+                    'fullpage', 'inputenc'):
+                    pass
+                else:
+                    out(line+'\n')
+
+        
+    #////////////////////////////////////////////////////////////
+    #{ Chapters
+    #////////////////////////////////////////////////////////////
+
+    def write_module(self, out, doc):
+        self.write_header(out, doc)
+        self.write_start_of(out, 'Module Description')
+
+        # Add this module to the index.
+        out('    ' + self.indexterm(doc, 'start'))
+
+        # Add a section marker.
+        out(self.section('%s %s' % (self.doc_kind(doc),
+                                    doc.canonical_name)))
+
+        # Label our current location.
+        out('    \\label{%s}\n' % self.label(doc))
+
+        # Add the module's description.
+        if doc.descr not in (None, UNKNOWN):
+            out(self.docstring_to_latex(doc.descr))
+
+        # Add version, author, warnings, requirements, notes, etc.
+        self.write_standard_fields(out, doc)
+
+        # If it's a package, list the sub-modules.
+        if doc.submodules != UNKNOWN and doc.submodules:
+            self.write_module_list(out, doc)
+
+        # Contents.
+        if self._list_classes_separately:
+            self.write_class_list(out, doc)
+        self.write_func_list(out, 'Functions', doc, 'function')
+        self.write_var_list(out, 'Variables', doc, 'other')
+
+        # Class list.
+        if not self._list_classes_separately:
+            classes = doc.select_variables(imported=False, value_type='class',
+                                           public=self._public_filter)
+            for var_doc in classes:
+                self.write_class(out, var_doc.value)
+
+        # Mark the end of the module (for the index)
+        out('    ' + self.indexterm(doc, 'end'))
+
+    def write_class(self, out, doc):
+        if self._list_classes_separately:
+            self.write_header(out, doc)
+        self.write_start_of(out, 'Class Description')
+
+        # Add this class to the index.
+        out('    ' + self.indexterm(doc, 'start'))
+
+        # Add a section marker.
+        if self._list_classes_separately:
+            seclevel = 0
+            out(self.section('%s %s' % (self.doc_kind(doc),
+                                        doc.canonical_name), seclevel))
+        else:
+            seclevel = 1
+            out(self.section('%s %s' % (self.doc_kind(doc),
+                                        doc.canonical_name[-1]), seclevel))
+
+        # Label our current location.
+        out('    \\label{%s}\n' % self.label(doc))
+
+        # Add our base list.
+        if doc.bases not in (UNKNOWN, None) and len(doc.bases) > 0:
+            out(self.base_tree(doc))
+
+        # The class's known subclasses
+        if doc.subclasses not in (UNKNOWN, None) and len(doc.subclasses) > 0:
+            sc_items = [plaintext_to_latex('%s' % sc.canonical_name)
+                        for sc in doc.subclasses]
+            out(self._descrlist(sc_items, 'Known Subclasses', short=1))
+
+        # The class's description.
+        if doc.descr not in (None, UNKNOWN):
+            out(self.docstring_to_latex(doc.descr))
+
+        # Version, author, warnings, requirements, notes, etc.
+        self.write_standard_fields(out, doc)
+
+        # Contents.
+        self.write_func_list(out, 'Methods', doc, 'method',
+                             seclevel+1)
+        self.write_var_list(out, 'Properties', doc,
+                            'property', seclevel+1)
+        self.write_var_list(out, 'Class Variables', doc, 
+                            'classvariable', seclevel+1)
+        self.write_var_list(out, 'Instance Variables', doc, 
+                            'instancevariable', seclevel+1)
+
+        # Mark the end of the class (for the index)
+        out('    ' + self.indexterm(doc, 'end'))
+
+    #////////////////////////////////////////////////////////////
+    #{ Module hierarchy trees
+    #////////////////////////////////////////////////////////////
+    
+    def write_module_tree(self, out):
+        modules = [doc for doc in self.valdocs
+                   if isinstance(doc, ModuleDoc)]
+        if not modules: return
+        
+        # Write entries for all top-level modules/packages.
+        out('\\begin{itemize}\n')
+        out('\\setlength{\\parskip}{0ex}\n')
+        for doc in modules:
+            if (doc.package in (None, UNKNOWN) or
+                doc.package not in self.valdocs):
+                self.write_module_tree_item(out, doc)
+        return s +'\\end{itemize}\n'
+
+    def write_module_list(self, out, doc):
+        if len(doc.submodules) == 0: return
+        self.write_start_of(out, 'Modules')
+        
+        out(self.section('Modules', 1))
+        out('\\begin{itemize}\n')
+        out('\\setlength{\\parskip}{0ex}\n')
+
+        for group_name in doc.group_names():
+            if not doc.submodule_groups[group_name]: continue
+            if group_name:
+                out('  \\item \\textbf{%s}\n' % group_name)
+                out('  \\begin{itemize}\n')
+            for submodule in doc.submodule_groups[group_name]:
+                self.write_module_tree_item(out, submodule)
+            if group_name:
+                out('  \end{itemize}\n')
+
+        out('\\end{itemize}\n\n')
+
+    def write_module_tree_item(self, out, doc, depth=0):
+        """
+        Helper function for L{write_module_tree} and L{write_module_list}.
+        
+        @rtype: C{string}
+        """
+        out(' '*depth + '\\item \\textbf{')
+        out(plaintext_to_latex(doc.canonical_name[-1]) +'}')
+        if doc.summary not in (None, UNKNOWN):
+            out(': %s\n' % self.docstring_to_latex(doc.summary))
+        if self._crossref:
+            out('\n  \\textit{(Section \\ref{%s}' % self.label(doc))
+            out(', p.~\\pageref{%s})}\n\n' % self.label(doc))
+        if doc.submodules != UNKNOWN and doc.submodules:
+            out(' '*depth + '  \\begin{itemize}\n')
+            out(' '*depth + '\\setlength{\\parskip}{0ex}\n')
+            for submodule in doc.submodules:
+                self.write_module_tree_item(out, submodule, depth+4)
+            out(' '*depth + '  \\end{itemize}\n')
+
+    #////////////////////////////////////////////////////////////
+    #{ Base class trees
+    #////////////////////////////////////////////////////////////
+
+    def base_tree(self, doc, width=None, linespec=None):
+        if width is None:
+            width = self._find_tree_width(doc)+2
+            linespec = []
+            s = ('&'*(width-4)+'\\multicolumn{2}{l}{\\textbf{%s}}\n' %
+                   plaintext_to_latex('%s'%self._base_name(doc)))
+            s += '\\end{tabular}\n\n'
+            top = 1
+        else:
+            s = self._base_tree_line(doc, width, linespec)
+            top = 0
+        
+        if isinstance(doc, ClassDoc):
+            for i in range(len(doc.bases)-1, -1, -1):
+                base = doc.bases[i]
+                spec = (i > 0)
+                s = self.base_tree(base, width, [spec]+linespec) + s
+
+        if top:
+            s = '\\begin{tabular}{%s}\n' % (width*'c') + s
+
+        return s
+
+    def _base_name(self, doc):
+        if doc.canonical_name is None:
+            if doc.parse_repr is not None:
+                return doc.parse_repr
+            else:
+                return '??'
+        else:
+            return '%s' % doc.canonical_name
+
+    def _find_tree_width(self, doc):
+        if not isinstance(doc, ClassDoc): return 2
+        width = 2
+        for base in doc.bases:
+            width = max(width, self._find_tree_width(base)+2)
+        return width
+
+    def _base_tree_line(self, doc, width, linespec):
+        base_name = plaintext_to_latex(self._base_name(doc))
+        
+        # linespec is a list of booleans.
+        s = '%% Line for %s, linespec=%s\n' % (base_name, linespec)
+
+        labelwidth = width-2*len(linespec)-2
+
+        # The base class name.
+        s += ('\\multicolumn{%s}{r}{' % labelwidth)
+        s += '\\settowidth{\\BCL}{%s}' % base_name
+        s += '\\multirow{2}{\\BCL}{%s}}\n' % base_name
+
+        # The vertical bars for other base classes (top half)
+        for vbar in linespec:
+            if vbar: s += '&&\\multicolumn{1}{|c}{}\n'
+            else: s += '&&\n'
+
+        # The horizontal line.
+        s += '  \\\\\\cline{%s-%s}\n' % (labelwidth+1, labelwidth+1)
+
+        # The vertical bar for this base class.
+        s += '  ' + '&'*labelwidth
+        s += '\\multicolumn{1}{c|}{}\n'
+
+        # The vertical bars for other base classes (bottom half)
+        for vbar in linespec:
+            if vbar: s += '&\\multicolumn{1}{|c}{}&\n'
+            else: s += '&&\n'
+        s += '  \\\\\n'
+
+        return s
+        
+    #////////////////////////////////////////////////////////////
+    #{ Class List
+    #////////////////////////////////////////////////////////////
+    
+    def write_class_list(self, out, doc):
+        groups = [(plaintext_to_latex(group_name),
+                   doc.select_variables(group=group_name, imported=False,
+                                        value_type='class',
+                                        public=self._public_filter))
+                  for group_name in doc.group_names()]
+
+        # Discard any empty groups; and return if they're all empty.
+        groups = [(g,vars) for (g,vars) in groups if vars]
+        if not groups: return
+
+        # Write a header.
+        self.write_start_of(out, 'Classes')
+        out(self.section('Classes', 1))
+        out('\\begin{itemize}')
+        out('  \\setlength{\\parskip}{0ex}\n')
+
+        for name, var_docs in groups:
+            if name:
+                out('  \\item \\textbf{%s}\n' % name)
+                out('  \\begin{itemize}\n')
+            # Add the lines for each class
+            for var_doc in var_docs:
+                self.write_class_list_line(out, var_doc)
+            if name:
+                out('  \\end{itemize}\n')
+
+        out('\\end{itemize}\n')
+
+    def write_class_list_line(self, out, var_doc):
+        if var_doc.value in (None, UNKNOWN): return # shouldn't happen
+        doc = var_doc.value
+        out('  ' + '\\item \\textbf{')
+        out(plaintext_to_latex(var_doc.name) + '}')
+        if doc.summary not in (None, UNKNOWN):
+            out(': %s\n' % self.docstring_to_latex(doc.summary))
+        if self._crossref:
+            out(('\n  \\textit{(Section \\ref{%s}' % self.label(doc)))
+            out((', p.~\\pageref{%s})}\n\n' % self.label(doc)))
+        
+    #////////////////////////////////////////////////////////////
+    #{ Function List
+    #////////////////////////////////////////////////////////////
+    _FUNC_GROUP_HEADER = '\n\\large{\\textbf{\\textit{%s}}}\n\n'
+    
+    def write_func_list(self, out, heading, doc, value_type, seclevel=1):
+        # Divide all public variables of the given type into groups.
+        groups = [(plaintext_to_latex(group_name),
+                   doc.select_variables(group=group_name, imported=False,
+                                        value_type=value_type,
+                                        public=self._public_filter))
+                  for group_name in doc.group_names()]
+
+        # Discard any empty groups; and return if they're all empty.
+        groups = [(g,vars) for (g,vars) in groups if vars]
+        if not groups: return
+
+        # Write a header.
+        self.write_start_of(out, heading)
+        out('  '+self.section(heading, seclevel))
+
+        # Write a section for each group.
+        grouped_inh_vars = {}
+        for name, var_docs in groups:
+            self.write_func_group(out, doc, name, var_docs, grouped_inh_vars)
+
+        # Write a section for each inheritance pseudo-group (used if
+        # inheritance=='grouped')
+        if grouped_inh_vars:
+            for base in doc.mro():
+                if base in grouped_inh_vars:
+                    hdr = ('Inherited from %s' %
+                           plaintext_to_latex('%s' % base.canonical_name))
+                    if self._crossref and base in self.class_set:
+                        hdr += ('\\textit{(Section \\ref{%s})}' %
+                                self.label(base))
+                    out(self._FUNC_GROUP_HEADER % (hdr))
+                    for var_doc in grouped_inh_vars[base]:
+                        self.write_func_list_box(out, var_doc)
+
+    def write_func_group(self, out, doc, name, var_docs, grouped_inh_vars):
+        # Split up the var_docs list, according to the way each var
+        # should be displayed:
+        #   - listed_inh_vars -- for listed inherited variables.
+        #   - grouped_inh_vars -- for grouped inherited variables.
+        #   - normal_vars -- for all other variables.
+        listed_inh_vars = {}
+        normal_vars = []
+        for var_doc in var_docs:
+            if var_doc.container != doc:
+                base = var_doc.container
+                if (base not in self.class_set or
+                    self._inheritance == 'listed'):
+                    listed_inh_vars.setdefault(base,[]).append(var_doc)
+                elif self._inheritance == 'grouped':
+                    grouped_inh_vars.setdefault(base,[]).append(var_doc)
+                else:
+                    normal_vars.append(var_doc)
+            else:
+                normal_vars.append(var_doc)
+            
+        # Write a header for the group.
+        if name:
+            out(self._FUNC_GROUP_HEADER % name)
+        # Write an entry for each normal var:
+        for var_doc in normal_vars:
+            self.write_func_list_box(out, var_doc)
+        # Write a subsection for inherited vars:
+        if listed_inh_vars:
+            self.write_func_inheritance_list(out, doc, listed_inh_vars)
+
+    def write_func_inheritance_list(self, out, doc, listed_inh_vars):
+        for base in doc.mro():
+            if base not in listed_inh_vars: continue
+            #if str(base.canonical_name) == 'object': continue
+            var_docs = listed_inh_vars[base]
+            if self._public_filter:
+                var_docs = [v for v in var_docs if v.is_public]
+            if var_docs:
+                hdr = ('Inherited from %s' %
+                       plaintext_to_latex('%s' % base.canonical_name))
+                if self._crossref and base in self.class_set:
+                    hdr += ('\\textit{(Section \\ref{%s})}' %
+                            self.label(base))
+                out(self._FUNC_GROUP_HEADER % hdr)
+                out('\\begin{quote}\n')
+                out('%s\n' % ', '.join(
+                    ['%s()' % plaintext_to_latex(var_doc.name)
+                     for var_doc in var_docs]))
+                out('\\end{quote}\n')
+            
+    def write_func_list_box(self, out, var_doc):
+        func_doc = var_doc.value
+        is_inherited = (var_doc.overrides not in (None, UNKNOWN))
+
+        # nb: this gives the containing section, not a reference
+        # directly to the function.
+        if not is_inherited:
+            out('    \\label{%s}\n' % self.label(func_doc))
+            out('    %s\n' % self.indexterm(func_doc))
+
+        # Start box for this function.
+        out('    \\vspace{0.5ex}\n\n')
+        out('\\hspace{.8\\funcindent}')
+        out('\\begin{boxedminipage}{\\funcwidth}\n\n')
+
+        # Function signature.
+        out('    %s\n\n' % self.function_signature(var_doc))
+
+        if (func_doc.docstring not in (None, UNKNOWN) and
+            func_doc.docstring.strip() != ''):
+            out('    \\vspace{-1.5ex}\n\n')
+            out('    \\rule{\\textwidth}{0.5\\fboxrule}\n')
+        
+        # Description
+        out("\\setlength{\\parskip}{2ex}\n")
+        if func_doc.descr not in (None, UNKNOWN):
+            out(self.docstring_to_latex(func_doc.descr, 4))
+
+        # Parameters
+        out("\\setlength{\\parskip}{1ex}\n")
+        if func_doc.arg_descrs or func_doc.arg_types:
+            # Find the longest name.
+            longest = max([0]+[len(n) for n in func_doc.arg_types])
+            for names, descrs in func_doc.arg_descrs:
+                longest = max([longest]+[len(n) for n in names])
+            # Table header.
+            out(' '*6+'\\textbf{Parameters}\n')
+            out('      \\vspace{-1ex}\n\n')
+            out(' '*6+'\\begin{quote}\n')
+            out('        \\begin{Ventry}{%s}\n\n' % (longest*'x'))
+            # Add params that have @type but not @param info:
+            arg_descrs = list(func_doc.arg_descrs)
+            args = set()
+            for arg_names, arg_descr in arg_descrs:
+                args.update(arg_names)
+            for arg in var_doc.value.arg_types:
+                if arg not in args:
+                    arg_descrs.append( ([arg],None) )
+            # Display params
+            for (arg_names, arg_descr) in arg_descrs:
+                arg_name = plaintext_to_latex(', '.join(arg_names))
+                out('%s\\item[%s]\n\n' % (' '*10, arg_name))
+                if arg_descr:
+                    out(self.docstring_to_latex(arg_descr, 10))
+                for arg_name in arg_names:
+                    arg_typ = func_doc.arg_types.get(arg_name)
+                    if arg_typ is not None:
+                        if len(arg_names) == 1:
+                            lhs = 'type'
+                        else:
+                            lhs = 'type of %s' % arg_name
+                        rhs = self.docstring_to_latex(arg_typ).strip()
+                        out('%s{\\it (%s=%s)}\n\n' % (' '*12, lhs, rhs))
+            out('        \\end{Ventry}\n\n')
+            out(' '*6+'\\end{quote}\n\n')
+                
+        # Returns
+        rdescr = func_doc.return_descr
+        rtype = func_doc.return_type
+        if rdescr not in (None, UNKNOWN) or rtype not in (None, UNKNOWN):
+            out(' '*6+'\\textbf{Return Value}\n')
+            out('    \\vspace{-1ex}\n\n')
+            out(' '*6+'\\begin{quote}\n')
+            if rdescr not in (None, UNKNOWN):
+                out(self.docstring_to_latex(rdescr, 6))
+                if rtype not in (None, UNKNOWN):
+                    out(' '*6+'{\\it (type=%s)}\n\n' %
+                        self.docstring_to_latex(rtype, 6).strip())
+            elif rtype not in (None, UNKNOWN):
+                out(self.docstring_to_latex(rtype, 6))
+            out(' '*6+'\\end{quote}\n\n')
+
+        # Raises
+        if func_doc.exception_descrs not in (None, UNKNOWN, [], ()):
+            out(' '*6+'\\textbf{Raises}\n')
+            out('    \\vspace{-1ex}\n\n')
+            out(' '*6+'\\begin{quote}\n')
+            out('        \\begin{description}\n\n')
+            for name, descr in func_doc.exception_descrs:
+                out(' '*10+'\\item[\\texttt{%s}]\n\n' %
+                    plaintext_to_latex('%s' % name))
+                out(self.docstring_to_latex(descr, 10))
+            out('        \\end{description}\n\n')
+            out(' '*6+'\\end{quote}\n\n')
+
+        ## Overrides
+        if var_doc.overrides not in (None, UNKNOWN):
+            out('      Overrides: ' +
+                plaintext_to_latex('%s'%var_doc.overrides.canonical_name))
+            if (func_doc.docstring in (None, UNKNOWN) and
+                var_doc.overrides.value.docstring not in (None, UNKNOWN)):
+                out(' \textit{(inherited documentation)}')
+            out('\n\n')
+
+        # Add version, author, warnings, requirements, notes, etc.
+        self.write_standard_fields(out, func_doc)
+
+        out('    \\end{boxedminipage}\n\n')
+
+    def function_signature(self, var_doc):
+        func_doc = var_doc.value
+        func_name = var_doc.name
+        
+        # This should never happen, but just in case:
+        if func_doc in (None, UNKNOWN):
+            return ('\\raggedright \\textbf{%s}(...)' %
+                    plaintext_to_latex(func_name))
+            
+        if func_doc.posargs == UNKNOWN:
+            args = ['...']
+        else:
+            args = [self.func_arg(name, default) for (name, default)
+                    in zip(func_doc.posargs, func_doc.posarg_defaults)]
+        if func_doc.vararg:
+            if func_doc.vararg == '...':
+                args.append('\\textit{...}')
+            else:
+                args.append('*\\textit{%s}' %
+                            plaintext_to_latex(func_doc.vararg))
+        if func_doc.kwarg:
+            args.append('**\\textit{%s}' %
+                        plaintext_to_latex(func_doc.kwarg))
+        return ('\\raggedright \\textbf{%s}(%s)' %
+                (plaintext_to_latex(func_name), ', '.join(args)))
+
+    def func_arg(self, name, default):
+        s = '\\textit{%s}' % plaintext_to_latex(self._arg_name(name))
+        if default is not None:
+            s += '={\\tt %s}' % default.summary_pyval_repr().to_latex(None)
+        return s
+    
+    def _arg_name(self, arg):
+        if isinstance(arg, basestring):
+            return arg
+        elif len(arg) == 1:
+            return '(%s,)' % self._arg_name(arg[0])
+        else:
+            return '(%s)' % (', '.join([self._arg_name(a) for a in arg]))
+
+    #////////////////////////////////////////////////////////////
+    #{ Variable List
+    #////////////////////////////////////////////////////////////
+    _VAR_GROUP_HEADER = '\\multicolumn{2}{|l|}{\\textit{%s}}\\\\\n'
+
+    # Also used for the property list.
+    def write_var_list(self, out, heading, doc, value_type, seclevel=1):
+        groups = [(plaintext_to_latex(group_name),
+                   doc.select_variables(group=group_name, imported=False,
+                                        value_type=value_type,
+                                        public=self._public_filter))
+                  for group_name in doc.group_names()]
+
+        # Discard any empty groups; and return if they're all empty.
+        groups = [(g,vars) for (g,vars) in groups if vars]
+        if not groups: return
+
+        # Write a header.
+        self.write_start_of(out, heading)
+        out('  '+self.section(heading, seclevel))
+
+        # [xx] without this, there's a huge gap before the table -- why??
+        out('    \\vspace{-1cm}\n')
+        
+        out('\\hspace{\\varindent}')
+        out('\\begin{longtable}')
+        out('{|p{\\varnamewidth}|')
+        out('p{\\vardescrwidth}|l}\n')
+        out('\\cline{1-2}\n')
+
+        # Set up the headers & footer (this makes the table span
+        # multiple pages in a happy way).
+        out('\\cline{1-2} ')
+        out('\\centering \\textbf{Name} & ')
+        out('\\centering \\textbf{Description}& \\\\\n')
+        out('\\cline{1-2}\n')
+        out('\\endhead')
+        out('\\cline{1-2}')
+        out('\\multicolumn{3}{r}{\\small\\textit{')
+        out('continued on next page}}\\\\')
+        out('\\endfoot')
+        out('\\cline{1-2}\n')
+        out('\\endlastfoot')
+
+        # Write a section for each group.
+        grouped_inh_vars = {}
+        for name, var_docs in groups:
+            self.write_var_group(out, doc, name, var_docs, grouped_inh_vars)
+
+        # Write a section for each inheritance pseudo-group (used if
+        # inheritance=='grouped')
+        if grouped_inh_vars:
+            for base in doc.mro():
+                if base in grouped_inh_vars:
+                    hdr = ('Inherited from %s' %
+                           plaintext_to_latex('%s' % base.canonical_name))
+                    if self._crossref and base in self.class_set:
+                        hdr += (' \\textit{(Section \\ref{%s})}' %
+                                self.label(base))
+                    out(self._VAR_GROUP_HEADER % (hdr))
+                    out('\\cline{1-2}\n')
+                    for var_doc in grouped_inh_vars[base]:
+                        if isinstance(var_doc.value3, PropertyDoc):
+                            self.write_property_list_line(out, var_doc)
+                        else:
+                            self.write_var_list_line(out, var_doc)
+    
+        out('\\end{longtable}\n\n')
+        
+    def write_var_group(self, out, doc, name, var_docs, grouped_inh_vars):
+        # Split up the var_docs list, according to the way each var
+        # should be displayed:
+        #   - listed_inh_vars -- for listed inherited variables.
+        #   - grouped_inh_vars -- for grouped inherited variables.
+        #   - normal_vars -- for all other variables.
+        listed_inh_vars = {}
+        normal_vars = []
+        for var_doc in var_docs:
+            if var_doc.container != doc:
+                base = var_doc.container
+                if (base not in self.class_set or
+                    self._inheritance == 'listed'):
+                    listed_inh_vars.setdefault(base,[]).append(var_doc)
+                elif self._inheritance == 'grouped':
+                    grouped_inh_vars.setdefault(base,[]).append(var_doc)
+                else:
+                    normal_vars.append(var_doc)
+            else:
+                normal_vars.append(var_doc)
+            
+        # Write a header for the group.
+        if name:
+            out(self._VAR_GROUP_HEADER % name)
+            out('\\cline{1-2}\n')
+        # Write an entry for each normal var:
+        for var_doc in normal_vars:
+            if isinstance(var_doc.value, PropertyDoc):
+                self.write_property_list_line(out, var_doc)
+            else:
+                self.write_var_list_line(out, var_doc)
+        # Write a subsection for inherited vars:
+        if listed_inh_vars:
+            self.write_var_inheritance_list(out, doc, listed_inh_vars)
+
+    def write_var_inheritance_list(self, out, doc, listed_inh_vars):
+        for base in doc.mro():
+            if base not in listed_inh_vars: continue
+            #if str(base.canonical_name) == 'object': continue
+            var_docs = listed_inh_vars[base]
+            if self._public_filter:
+                var_docs = [v for v in var_docs if v.is_public]
+            if var_docs:
+                hdr = ('Inherited from %s' %
+                       plaintext_to_latex('%s' % base.canonical_name))
+                if self._crossref and base in self.class_set:
+                    hdr += (' \\textit{(Section \\ref{%s})}' %
+                            self.label(base))
+                out(self._VAR_GROUP_HEADER % hdr)
+                out('\\multicolumn{2}{|p{\\varwidth}|}{'
+                    '\\raggedright %s}\\\\\n' %
+                    ', '.join(['%s' % plaintext_to_latex(var_doc.name)
+                               for var_doc in var_docs]))
+                out('\\cline{1-2}\n')
+
+        
+    def write_var_list_line(self, out, var_doc):
+        out('\\raggedright ')
+        out(plaintext_to_latex(var_doc.name, nbsp=True, breakany=True))
+        out(' & ')
+        has_descr = var_doc.descr not in (None, UNKNOWN)
+        has_type = var_doc.type_descr not in (None, UNKNOWN)
+        has_value = var_doc.value is not UNKNOWN
+        if has_type or has_value:
+            out('\\raggedright ')
+        if has_descr:
+            out(self.docstring_to_latex(var_doc.descr, 10).strip())
+            if has_type or has_value: out('\n\n')
+        if has_value:
+            out('\\textbf{Value:} \n{\\tt %s}' %
+                var_doc.value.summary_pyval_repr().to_latex(None))
+        if has_type:
+            ptype = self.docstring_to_latex(var_doc.type_descr, 12).strip()
+            out('%s{\\it (type=%s)}' % (' '*12, ptype))
+        out('&\\\\\n')
+        out('\\cline{1-2}\n')
+
+    def write_property_list_line(self, out, var_doc):
+        prop_doc = var_doc.value
+        out('\\raggedright ')
+        out(plaintext_to_latex(var_doc.name, nbsp=True, breakany=True))
+        out(' & ')
+        has_descr = prop_doc.descr not in (None, UNKNOWN)
+        has_type = prop_doc.type_descr not in (None, UNKNOWN)
+        if has_descr or has_type:
+            out('\\raggedright ')
+        if has_descr:
+            out(self.docstring_to_latex(prop_doc.descr, 10).strip())
+            if has_type: out('\n\n')
+        if has_type:
+            ptype = self.docstring_to_latex(prop_doc.type_descr, 12).strip()
+            out('%s{\\it (type=%s)}' % (' '*12, ptype))
+        # [xx] List the fget/fset/fdel functions?
+        out('&\\\\\n')
+        out('\\cline{1-2}\n')
+
+    #////////////////////////////////////////////////////////////
+    #{ Standard Fields
+    #////////////////////////////////////////////////////////////
+
+    # Copied from HTMLWriter:
+    def write_standard_fields(self, out, doc):
+        fields = []
+        field_values = {}
+        
+        #if _sort_fields: fields = STANDARD_FIELD_NAMES [XX]
+        
+        for (field, arg, descr) in doc.metadata:
+            if field not in field_values:
+                fields.append(field)
+            if field.takes_arg:
+                subfields = field_values.setdefault(field,{})
+                subfields.setdefault(arg,[]).append(descr)
+            else:
+                field_values.setdefault(field,[]).append(descr)
+
+        for field in fields:
+            if field.takes_arg:
+                for arg, descrs in field_values[field].items():
+                    self.write_standard_field(out, doc, field, descrs, arg)
+                                              
+            else:
+                self.write_standard_field(out, doc, field, field_values[field])
+
+    def write_standard_field(self, out, doc, field, descrs, arg=''):
+        singular = field.singular
+        plural = field.plural
+        if arg:
+            singular += ' (%s)' % arg
+            plural += ' (%s)' % arg
+        out(self._descrlist([self.docstring_to_latex(d) for d in descrs],
+                            field.singular, field.plural, field.short))
+            
+    def _descrlist(self, items, singular, plural=None, short=0):
+        if plural is None: plural = singular
+        if len(items) == 0: return ''
+        if len(items) == 1 and singular is not None:
+            return '\\textbf{%s:} %s\n\n' % (singular, items[0])
+        if short:
+            s = '\\textbf{%s:}\n' % plural
+            items = [item.strip() for item in items]
+            return s + ',\n    '.join(items) + '\n\n'
+        else:
+            s = '\\textbf{%s:}\n' % plural
+            s += '\\begin{quote}\n'
+            s += '  \\begin{itemize}\n\n  \item\n'
+            s += '    \\setlength{\\parskip}{0.6ex}\n'
+            s += '\n\n  \item '.join(items)
+            return s + '\n\n\\end{itemize}\n\n\\end{quote}\n\n'
+
+
+    #////////////////////////////////////////////////////////////
+    #{ Docstring -> LaTeX Conversion
+    #////////////////////////////////////////////////////////////
+
+    # We only need one linker, since we don't use context:
+    class _LatexDocstringLinker(markup.DocstringLinker):
+        def translate_indexterm(self, indexterm):
+            indexstr = re.sub(r'["!|@]', r'"\1', indexterm.to_latex(self))
+            return ('\\index{%s}\\textit{%s}' % (indexstr, indexstr))
+        def translate_identifier_xref(self, identifier, label=None):
+            if label is None: label = markup.plaintext_to_latex(identifier)
+            return '\\texttt{%s}' % label
+    _docstring_linker = _LatexDocstringLinker()
+    
+    def docstring_to_latex(self, docstring, indent=0, breakany=0):
+        if docstring is None: return ''
+        return docstring.to_latex(self._docstring_linker, indent=indent,
+                                  hyperref=self._hyperref)
+    
+    #////////////////////////////////////////////////////////////
+    #{ Helpers
+    #////////////////////////////////////////////////////////////
+
+    def write_header(self, out, where):
+        out('%\n% API Documentation')
+        if self._prj_name: out(' for %s' % self._prj_name)
+        if isinstance(where, APIDoc):
+            out('\n%% %s %s' % (self.doc_kind(where), where.canonical_name))
+        else:
+            out('\n%% %s' % where)
+        out('\n%%\n%% Generated by epydoc %s\n' % epydoc.__version__)
+        out('%% [%s]\n%%\n' % time.asctime(time.localtime(time.time())))
+
+    def write_start_of(self, out, section_name):
+        out('\n' + 75*'%' + '\n')
+        out('%%' + ((71-len(section_name))/2)*' ')
+        out(section_name)
+        out(((72-len(section_name))/2)*' ' + '%%\n')
+        out(75*'%' + '\n\n')
+
+    def section(self, title, depth=0):
+        sec = self.SECTIONS[depth+self._top_section]
+        return (('%s\n\n' % sec) % plaintext_to_latex(title))                
+    
+    def sectionstar(self, title, depth):
+        sec = self.STARSECTIONS[depth+self._top_section]
+        return (('%s\n\n' % sec) % plaintext_to_latex(title))
+
+    def doc_kind(self, doc):
+        if isinstance(doc, ModuleDoc) and doc.is_package == True:
+            return 'Package'
+        elif (isinstance(doc, ModuleDoc) and
+              doc.canonical_name[0].startswith('script')):
+            return 'Script'
+        elif isinstance(doc, ModuleDoc):
+            return 'Module'
+        elif isinstance(doc, ClassDoc):
+            return 'Class'
+        elif isinstance(doc, ClassMethodDoc):
+            return 'Class Method'
+        elif isinstance(doc, StaticMethodDoc):
+            return 'Static Method'
+        elif isinstance(doc, RoutineDoc):
+            if isinstance(self.docindex.container(doc), ClassDoc):
+                return 'Method'
+            else:
+                return 'Function'
+        else:
+            return 'Variable'
+
+    def indexterm(self, doc, pos='only'):
+        """Mark a term or section for inclusion in the index."""
+        if not self._index: return ''
+        if isinstance(doc, RoutineDoc) and not self._index_functions:
+            return ''
+
+        pieces = []
+        while doc is not None:
+            if doc.canonical_name == UNKNOWN:
+                return '' # Give up.
+            pieces.append('%s \\textit{(%s)}' %
+                          (plaintext_to_latex('%s'%doc.canonical_name),
+                           self.doc_kind(doc).lower()))
+            doc = self.docindex.container(doc)
+            if doc == UNKNOWN:
+                return '' # Give up.
+
+        pieces.reverse()
+        if pos == 'only':
+            return '\\index{%s}\n' % '!'.join(pieces)
+        elif pos == 'start':
+            return '\\index{%s|(}\n' % '!'.join(pieces)
+        elif pos == 'end':
+            return '\\index{%s|)}\n' % '!'.join(pieces)
+        else:
+            raise AssertionError('Bad index position %s' % pos)
+        
+    def label(self, doc):
+        return ':'.join(doc.canonical_name)
+
+    #: Map the Python encoding representation into mismatching LaTeX ones.
+    latex_encodings = {
+        'utf-8': 'utf8',
+    }
+
+    def get_latex_encoding(self):
+        """
+        @return: The LaTeX representation of the selected encoding.
+        @rtype: C{str}
+        """
+        enc = self._encoding.lower()
+        return self.latex_encodings.get(enc, enc)