Changeset 2751 for vendor

Timestamp:

10/22/2008 01:27:48 PM (3 months ago)

Author:

guyer

Message:

Load /Users/guyer/Documents/Python/epydoc-r1810 into
vendor/epydoc/current.

Location:

vendor/epydoc/current/src/epydoc

Files:

• cli.py (modified) (4 diffs)
• docintrospecter.py (modified) (3 diffs)
• docwriter/latex.py (modified) (39 diffs)
• docwriter/latex_sty.py (modified) (21 diffs)

vendor/epydoc/current/src/epydoc/cli.py

@@ -5 +5 @@
 # URL: <http://epydoc.sf.net>
 #
-# $Id: cli.py 1801 2008-02-27 00:20:24Z edloper $
+# $Id: cli.py 1807 2008-03-04 02:32:58Z edloper $
 
 """
@@ -1057 +1057 @@
     log.info('%r pdfdriver selected' % options.pdfdriver)
     
-    from epydoc.docwriter.latex import LatexWriter
+    from epydoc.docwriter.latex import LatexWriter, show_latex_warnings
     latex_writer = LatexWriter(docindex, **options.__dict__)
-    latex_writer.write(latex_target)
+    try:
+        latex_writer.write(latex_target)
+    except IOError, e:
+        log.error(e)
+        log.end_progress()
+        log.start_progress()
+        log.end_progress()
+        return
     log.end_progress()
 
@@ -1120 +1127 @@
                 # changed what page some things are on.
                 running = latex_command
-                if _RERUN_LATEX_RE.match(out):
+                if _RERUN_LATEX_RE.search(out):
                     log.progress(step/steps, '%s (Third pass)' % LaTeX)
                     out, err = run_subprocess('%s api.tex' % latex_command)
@@ -1126 +1133 @@
                 # A fourth path should (almost?) never be necessary.
                 running = latex_command
-                if _RERUN_LATEX_RE.match(out):
+                if _RERUN_LATEX_RE.search(out):
                     log.progress(step/steps, '%s (Fourth pass)' % LaTeX)
-                    run_subprocess('%s api.tex' % latex_command)
+                    out, err = run_subprocess('%s api.tex' % latex_command)
                 step += 1
+
+                # Show the output, if verbosity is high:
+                if options.verbosity > 2 or epydoc.DEBUG:
+                    show_latex_warnings(out)
 
             # If requested, convert to postscript.

vendor/epydoc/current/src/epydoc/docintrospecter.py

@@ -5 +5 @@
 # URL: <http://epydoc.sf.net>
 #
-# $Id: docintrospecter.py 1722 2008-02-15 01:11:18Z edloper $
+# $Id: docintrospecter.py 1810 2008-03-31 03:22:51Z edloper $
 
 """
@@ -268 +268 @@
         # value if it's defined in this module.
         container = get_containing_module(child)
-        if ((container is not None and
-             container == name_without_primes) or
-            (public_names is not None and
-             child_name in public_names)):
+        if (((container is not None and
+              container == name_without_primes) or
+             (public_names is not None and
+              child_name in public_names))
+            and not inspect.ismodule(child)):
             # Local variable.
             child_val_doc = introspect_docs(child, context=module_doc,
@@ -280 +281 @@
                                         container=module_doc,
                                         docs_extracted_by='introspecter')
-        elif container is None or module_doc.canonical_name is UNKNOWN:
+        elif ((container is None or module_doc.canonical_name is UNKNOWN)
+              and not inspect.ismodule(child)):
 
             # Don't introspect stuff "from __future__"

vendor/epydoc/current/src/epydoc/docwriter/latex.py

@@ -4 +4 @@
 #
 # Created [01/30/01 05:18 PM]
-# $Id: latex.py 1799 2008-02-27 00:01:42Z edloper $
+# $Id: latex.py 1809 2008-03-05 18:40:49Z edloper $
 #
 
@@ -46 +46 @@
         # Process keyword arguments
         self._show_private = kwargs.get('show_private', 0)
-        self._prj_name = kwargs.get('prj_name', None) or 'API Documentation'
+        self._prj_name = kwargs.get('prj_name', None)
         self._show_crossrefs = kwargs.get('crossref', 1)
         self._index = kwargs.get('index', 1)
@@ -125 +125 @@
                 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):
+            elif isinstance(val_doc, ClassDoc):
                 filename = '%s-class.tex' % val_doc.canonical_name
                 self._write(self.write_class, directory, filename, val_doc)
@@ -205 +204 @@
         @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
+        return 1 + len([doc for doc in self.valdocs
+                        if isinstance(doc, (ClassDoc, ModuleDoc))])
         
     def _mkdir(self, directory):
@@ -230 +225 @@
         self.write_preamble(out)
         out('\n\\begin{document}\n\n')
-        self.write_start_of(out, 'Header')
+        out(self.start_of('Header'))
 
         # Write the title.
-        self.write_start_of(out, 'Title')
-        out('\\title{%s}\n' % plaintext_to_latex(self._prj_name, 1))
+        out(self.start_of('Title'))
+        out('\\title{%s}\n' % plaintext_to_latex(
+            self._prj_name or 'API Documentation', 1))
         out('\\author{API Documentation}\n')
         out('\\maketitle\n')
 
         # Add a table of contents.
-        self.write_start_of(out, 'Table of Contents')
+        out(self.start_of('Table of Contents'))
         out('\\addtolength{\\parskip}{-1ex}\n')
         out('\\tableofcontents\n')
@@ -245 +241 @@
 
         # Include documentation files.
-        self.write_start_of(out, 'Includes')
+        out(self.start_of('Includes'))
         for val_doc in self.valdocs:
             if isinstance(val_doc, ModuleDoc):
@@ -259 +255 @@
         # Add the index, if requested.
         if self._index:
-            self.write_start_of(out, 'Index')
+            out(self.start_of('Index'))
             out('\\printindex\n\n')
 
         # Add the footer.
-        self.write_start_of(out, 'Footer')
+        out(self.start_of('Footer'))
         out('\\end{document}\n\n')
 
@@ -308 +304 @@
     def write_module(self, out, doc):
         self.write_header(out, doc)
-        self.write_start_of(out, 'Module Description')
+        out(self.start_of('Section Heading', doc))
 
         # Add this module to the index.
-        out('    ' + self.indexterm(doc, 'start'))
+        out(self.indexterm(doc, 'start'))
 
         # Add a section marker.
@@ -320 +316 @@
         # Add the module's description.
         if doc.descr not in (None, UNKNOWN):
-            out(' '*4 + '\\begin{EpydocModuleDescription}%\n')
+            out(self.start_of('Description', doc))
+            out('\\begin{EpydocModuleDescription}%\n')
             out(self.docstring_to_latex(doc.descr, doc, 4))
-            out(' '*4 + '\\end{EpydocModuleDescription}\n')
+            out('\\end{EpydocModuleDescription}\n')
 
         # Add version, author, warnings, requirements, notes, etc.
-        self.write_standard_fields(out, doc)
+        out(self.metadata(doc))
 
         # If it's a package, list the sub-modules.
@@ -343 +340 @@
             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)
+            if classes:
+                out(self.start_of('Classes', doc))
+                for var_doc in classes:
+                    # don't use \include -- can't be nested.
+                    out('\\input{%s-class}\n' % var_doc.value.canonical_name)
 
         # Mark the end of the module (for the index)
-        out('    ' + self.indexterm(doc, 'end'))
+        out(self.start_of('Footer', doc))
+        out(self.indexterm(doc, 'end'))
 
     def render_graph(self, graph):
@@ -354 +355 @@
         return graph.to_latex(self._directory) or ''
 
-    def write_class(self, out, doc, short_name=None):
-        if short_name is None: short_name = doc.canonical_name[-1]
-        
+    def write_class(self, out, doc):
+        self.write_header(out, doc)
+        out(self.start_of('Section Heading', doc))
+
+        # Add this class to the index.
+        out(self.indexterm(doc, 'start'))
+
+        # Decide on our short (contextualized) name.
         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.
+            short_name = doc.canonical_name
+        if doc.defining_module not in (None, UNKNOWN):
+            short_name = doc.canonical_name.contextualize(
+                doc.defining_module.canonical_name)
+        else:
+            short_name = doc.canonical_name[-1]
+
+        # Decidie on our initial section level.
         if self._list_classes_separately:
             seclevel = 0
-            out(self.section('%s %s' % (self.doc_kind(doc),
-                                        _dotted(doc.canonical_name)), 
-                             seclevel, ref=doc))
         else:
             seclevel = 1
-            out(self.section('%s %s' % (self.doc_kind(doc),
-                                        _dotted(short_name)), 
-                             seclevel, ref=doc))
-
+
+        # Add a section marker.
+        out(self.section('%s %s' % (self.doc_kind(doc), _dotted(short_name)),
+                         seclevel, ref=doc))
+
+        # Display our base classes & subclasses
+        out(self.start_of('Class Tree', doc))
         if ((doc.bases not in (UNKNOWN, None) and len(doc.bases) > 0) or
             (doc.subclasses not in (UNKNOWN,None) and len(doc.subclasses)>0)):
@@ -399 +406 @@
                 sc_items = [_hyperlink(sc, '%s' % sc.canonical_name)
                             for sc in doc.subclasses]
+                out('{\\raggedright%\n')
                 out(self._descrlist(sc_items, 'Known Subclasses', short=1))
+                out('}%\n')
 
         # The class's description.
         if doc.descr not in (None, UNKNOWN):
-            out(' '*4 + '\\begin{EpydocClassDescription}\n')
-            out(self.docstring_to_latex(doc.descr, doc))
-            out(' '*4 + '\\end{EpydocClassDescription}\n')
+            out(self.start_of('Description', doc))
+            out('\\begin{EpydocClassDescription}%\n')
+            out(self.docstring_to_latex(doc.descr, doc, 4))
+            out('\\end{EpydocClassDescription}\n')
 
         # Version, author, warnings, requirements, notes, etc.
-        self.write_standard_fields(out, doc)
+        out(self.metadata(doc))
 
         # Contents.
@@ -423 +433 @@
 
         # Mark the end of the class (for the index)
-        out('    ' + self.indexterm(doc, 'end'))
+        out(self.start_of('Footer', doc))
+        out(self.indexterm(doc, 'end'))
 
         # Write any nested classes.  These will have their own
         # section (at the same level as this section)
-        for nested_class in doc.select_variables(imported=False,
-                                                 value_type='class',
-                                                 public=self._public_filter):
-            if (nested_class.value.canonical_name != UNKNOWN and
-                (nested_class.value.canonical_name[:-1] ==
-                 doc.canonical_name)):
-                self.write_class(out, nested_class.value,
-                                 DottedName(short_name,
-                                            nested_class.canonical_name[-1]))
+        if not self._list_classes_separately:
+            nested_classes = doc.select_variables(
+                    imported=False, value_type='class',
+                    public=self._public_filter)
+            if nested_classes:
+                out(self.start_of('Nested Classes', doc))
+                for nested_class in nested_classes:
+                    if (nested_class.value.canonical_name != UNKNOWN and
+                        (nested_class.value.canonical_name[:-1] ==
+                         doc.canonical_name)):
+                        # don't use \include -- can't be nested.
+                        out('\\input{%s-class}\n' %
+                            nested_class.value.canonical_name)
 
     #////////////////////////////////////////////////////////////
@@ -457 +472 @@
     def write_module_list(self, out, doc):
         if len(doc.submodules) == 0: return
-        self.write_start_of(out, 'Submodules')
+        out(self.start_of('Submodules', doc))
         
         out(self.section('Submodules', 1))
@@ -480 +495 @@
         @rtype: C{string}
         """
-        out(' '*depth + '\\item[%s]' % _hyperlink(doc, doc.canonical_name[-1]))
+        out(' '*depth + '\\item[%s]\n' %
+            _hyperlink(doc, doc.canonical_name[-1]))
 
         if doc.summary not in (None, UNKNOWN):
-            out(' %s\n' % self.docstring_to_latex(doc.summary, doc))
+            out(self.docstring_to_latex(doc.summary, doc, depth+2))
         out(self.crossref(doc) + '\n\n')
         if doc.submodules != UNKNOWN and doc.submodules:
@@ -499 +515 @@
             width = self._find_tree_width(doc)+2
             linespec = []
-            s = ('&'*(width-4)+'\\multicolumn{2}{l}{\\textbf{%s}}\n' %
+            s = ('  %% Class tree line for this class (%s)\n  ' %
+                 doc.canonical_name + '&'*(width-4) +
+                 '\\multicolumn{2}{l}{\\textbf{%s}}\n' %
                    _dotted('%s'%self._base_name(doc)))
             s += '\\end{tabular}\n\n'
@@ -535 +553 @@
 
     def _base_tree_line(self, doc, width, linespec):
+        # linespec is a list of booleans.
         base_name = _dotted(self._base_name(doc))
         
-        # linespec is a list of booleans.
-        s = '%% Line for %s, linespec=%s\n' % (base_name, linespec)
-
+        s = '  %% Class tree line for base "%s"\n' % self._base_name(doc)
         labelwidth = width-2*len(linespec)-2
 
         # The base class name.
-        s += ('\\multicolumn{%s}{r}{' % labelwidth)
-        s += '\\settowidth{\\EpydocBCL}{%s}' % base_name
-        s += ('\\multirow{2}{\\EpydocBCL}{%s}}\n' %
-              _hyperlink(doc, self._base_name(doc)))
+        s += '  \\multicolumn{%s}{r}{\n' % labelwidth
+        s += '      \\settowidth{\\EpydocBCL}{%s}\n' % base_name
+        s += '      \\multirow{2}{\\EpydocBCL}{\n'
+        s += '        %s}}\n' % _hyperlink(doc, self._base_name(doc))
 
         # The vertical bars for other base classes (top half)
         for vbar in linespec:
-            if vbar: s += '&&\\multicolumn{1}{|c}{}\n'
-            else: s += '&&\n'
+            if vbar: s += '    &&\\multicolumn{1}{|c}{}\n'
+            else: s += '    &&\n'
 
         # The horizontal line.
-        s += '  \\\\\\cline{%s-%s}\n' % (labelwidth+1, labelwidth+1)
+        s += '    \\\\\\cline{%s-%s}\n' % (labelwidth+1, labelwidth+1)
 
         # The vertical bar for this base class.
-        s += '  ' + '&'*labelwidth
+        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'
+            if vbar: s += '    &\\multicolumn{1}{|c}{}&\n'
+            else: s += '    &&\n'
+        
+        s += '    \\\\\n'
 
         return s
@@ -584 +602 @@
 
         # Write a header.
-        self.write_start_of(out, 'Classes')
+        out(self.start_of('Classes', doc))
         out(self.section('Classes', 1))
         out('\\begin{EpydocClassList}\n')
@@ -606 +624 @@
                                              var_doc.name))
         if doc.summary not in (None, UNKNOWN):
-            out(': %s\n' % self.docstring_to_latex(doc.summary, doc))
-        out(self.crossref(doc) + '\n\n')
+            out(': %\n' + self.docstring_to_latex(doc.summary, doc))
+        out(self.crossref(doc))
         
     #////////////////////////////////////////////////////////////
@@ -628 +646 @@
 
         # Write a header.
-        self.write_start_of(out, heading)
-        out('  '+self.section(heading, seclevel))
+        out(self.start_of(heading, doc))
+        out(self.section(heading, seclevel))
 
         out('\\begin{%s}\n' % list_type)
@@ -719 +737 @@
     #{ Function Details
     #////////////////////////////////////////////////////////////
+
+    def replace_par(self, out):
+        def new_out(s):
+            s = re.sub('(?m)\n([ \t]*\n)+', '\\par\n', s)
+            s = re.sub(r'\\par\b', r'\\EpydocPar', s)
+            s = re.sub(r'(?m)^([ \t]*)([^ \t].*)\\EpydocPar\n',
+                       r'\1\2\n\1\\EpydocPar\n', s)
+            out(s)
+        return new_out
     
     def write_function(self, out, var_doc):
@@ -728 +755 @@
         # directly to the function.
         if not is_inherited:
-            out('    %s%%\n' % self.indexterm(func_doc))
-
-        # This latex command takes 8 arguments.
-        out('\\EpydocFunction{%\n')
-
+            out('  %s' % self.indexterm(func_doc))
+
+        out('  \\EpydocFunction{%% <<< %s >>>\n' % var_doc.name)
+
+        # We're passing arguments using xkeyval, which is unhappy if
+        # the arguments contain \par.  So replace every occurence of
+        # \par with \EpydocPar (which is defined to just return \par).
+        out = self.replace_par(out)
+        
         # Argument 1: the function signature
-        out(self.function_signature(var_doc))
-        out('}{%\n')
+        out('    signature={%%\n%s    }' %
+            self.function_signature(var_doc))
 
         # Argument 2: the function description
         if func_doc.descr not in (None, UNKNOWN):
-            out(self.docstring_to_latex(func_doc.descr, func_doc, 4))
-        out('}{%\n')
+            out(',\n    description={%\n')
+            out(self.docstring_to_latex(func_doc.descr, func_doc, 6))
+            out('    }')
 
         # Argument 3: the function parameter descriptions
         if func_doc.arg_descrs or func_doc.arg_types:
+            out(',\n    parameters={%\n')
             self.write_function_parameters(out, var_doc)
-        out('}{%\n')
+            out('    }')
 
         # Argument 4: The return description
         if func_doc.return_descr not in (None, UNKNOWN):
-                out(self.docstring_to_latex(func_doc.return_descr,
-                                            func_doc, 6))
-        out('}{%\n')
+            out(',\n    returndescr={%\n')
+            out(self.docstring_to_latex(func_doc.return_descr, func_doc, 6))
+            out('    }')
         
         # Argument 5: The return type
         if func_doc.return_type not in (None, UNKNOWN):
-                out(self.docstring_to_latex(func_doc.return_type,
-                                            func_doc, 6).strip())
-        out('}{%\n')
+            out(',\n    returntype={%\n')
+            out(self.docstring_to_latex(func_doc.return_type, func_doc, 6))
+            out('    }')
 
         # Argument 6: The raises section
         if func_doc.exception_descrs not in (None, UNKNOWN, [], ()):
+            out(',\n    raises={%\n')
             out(' '*6+'\\begin{EpydocFunctionRaises}\n')
             for name, descr in func_doc.exception_descrs:
@@ -766 +800 @@
                     plaintext_to_latex('%s' % name))
                 out(self.docstring_to_latex(descr, func_doc, 10))
-            out(' '*6+'\\end{EpydocFunctionRaises}\n\n')
-        out('}{%\n')
+            out(' '*6+'\\end{EpydocFunctionRaises}\n')
+            out('    }')
 
         # Argument 7: The overrides section
         if var_doc.overrides not in (None, UNKNOWN):
+            out(',\n    overrides={%\n')
             out('\\EpydocFunctionOverrides')
             if (func_doc.docstring in (None, UNKNOWN) and
                 var_doc.overrides.value.docstring not in (None, UNKNOWN)):
                 out('[1]')
-            out('{%s}\n\n' 
+            out('{%s}\n' 
                 % _hyperlink(var_doc.overrides, 
                              '%s' % var_doc.overrides.canonical_name))
-        out('}{%\n')
+            out('    }')
 
         # Argument 8: The metadata section
-        self.write_standard_fields(out, func_doc)
-        out('}\n')
-            
+        metadata = self.metadata(func_doc, 6)
+        if metadata:
+            out(',\n    metadata={%%\n%s    }' % metadata)
+
+        out('}%\n')
 
     def write_function_parameters(self, out, var_doc):
@@ -804 +841 @@
         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))
+            out('%s\\item[%s]\n' % (' '*8, arg_name))
             if arg_descr:
                 out(self.docstring_to_latex(arg_descr, func_doc, 10))
@@ -817 +854 @@
                     else:
                         lhs = 'type of %s' % arg_name
-                    rhs = self.docstring_to_latex(arg_typ, func_doc).strip()
-                    out('%s{\\it (%s=%s)}\n\n' % (' '*12, lhs, rhs))
-        out(' '*6+'\\end{EpydocFunctionParameters}\n\n')
-        
-    def function_signature(self, var_doc):
+                    rhs = self.docstring_to_latex(arg_typ, func_doc, 14)
+                    out('%s\\textit{ (%s=%%\n%s%s)}\n' % (' '*12, lhs,
+                                                      rhs, ' '*12))
+        out(' '*6+'\\end{EpydocFunctionParameters}\n')
+        
+    def function_signature(self, var_doc, indent=6):
         func_doc = var_doc.value
         func_name = var_doc.name
 
-        s = ('\\begin{EpydocFunctionSignature}{%s}%%\n' %
-             _hypertarget(var_doc, func_name))
+        s = ('%s\\begin{EpydocFunctionSignature}%%\n%s  {%s}%%\n' %
+             (indent*' ', indent*' ', _hypertarget(var_doc, func_name)))
       
         # This should never happen, but just in case:
@@ -843 +881 @@
             if func_doc.kwarg:
                 args.append('\\KWArg{%s}' % plaintext_to_latex(func_doc.kwarg))