Software Público Brasileiro

#
# epydoc.py: epydoc LaTeX output generator
# Edward Loper
#
# Created [01/30/01 05:18 PM]
# $Id: latex.py 1621 2007-09-23 18:54:23Z edloper $
#

"""
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)