[Epydoc-commits] SF.net SVN: epydoc: [1793] trunk/epydoc/src/epydoc/docwriter

Revision: 1793
          http://epydoc.svn.sourceforge.net/epydoc/?rev=1793&view=rev
Author:   edloper
Date:     2008-02-26 09:11:38 -0800 (Tue, 26 Feb 2008)

Log Message:
-----------

- Use the xkeyval package to add two new keyword options to the epydoc
  sty file (title and creator), which are used to set the hyperref
  options pdftitle and pdfcreator.

- Use conditional test to decide whether the dvips or pdftex option
  should be pased to the hyperref package.  The generated latex output
  no longer hard-codes information about the driver (so the same
  latex output can be used by both latex and pdflatex).

- The preamble in the generated api.tex now *just* uses the selected
  epydoc sty package. (the \uepackage statements for the hyperref
  and graphicx packages were changed to \RequirePackage statements
  in epydoc-base.sty.)

- Fixed bug where nested classes were not being documented.

- Fixed several bugs with index generation

- Fixed \ProvidesClass statements in epydoc-*.sty files

Modified Paths:
--------------
    trunk/epydoc/src/epydoc/docwriter/latex.py
    trunk/epydoc/src/epydoc/docwriter/latex_sty.py

Modified: trunk/epydoc/src/epydoc/docwriter/latex.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/latex.py	2008-02-26 03:13:30 UTC (rev 1792)
+++ trunk/epydoc/src/epydoc/docwriter/latex.py	2008-02-26 17:11:38 UTC (rev 1793)
@@ -31,7 +31,6 @@
     PREAMBLE = [
         "\\documentclass{article}",
         "\\usepackage[%s]{%s}",
-        "\\usepackage{graphicx}",
         ]
 
     SECTIONS = ['\\part{%s}', '\\chapter{%s}', '\\section{%s}',
@@ -55,7 +54,6 @@
         self._exclude = kwargs.get('exclude', 1)
         self._list_submodules = kwargs.get('list_submodules', 1)
         self._sty = kwargs.get('sty')
-        self._pdfdriver = kwargs.get('pdfdriver', 'latex')
         self._top_section = 2
         self._index_functions = 1
         self._hyperref = 1
@@ -270,6 +268,8 @@
     def write_preamble(self, out):
         # If we're generating an index, add it to the preamble.
         options = []
+        options.append('creator={epydoc %s}' % epydoc.__version__)
+        options.append('title={%s}' % plaintext_to_latex(self._prj_name or ''))
         if self._index: options.append('index')
         if self._hyperlink: options.append('hyperlink')
         out('\n'.join(self.PREAMBLE) % (','.join(options),
@@ -283,21 +283,6 @@
         if self._hyperref:
             out('\\definecolor{UrlColor}{rgb}{0,0.08,0.45}\n')
             
-            if self._pdfdriver == 'pdflatex':
-                driver = 'pdftex'
-            elif self._pdfdriver == 'latex':
-                driver = 'dvips'
-            else:
-                raise ValueError('bad pdfdriver: %s' % self._pdfdriver)
-                
-            out('\\usepackage[%s, 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' %
-                (driver, self._prj_name or '', epydoc.__version__))
-            
         # If restructuredtext was used, then we need to extend
         # the prefix to include LatexTranslator.head_prefix.
         if 'restructuredtext' in epydoc.markup.MARKUP_LANGUAGES_USED:
@@ -370,7 +355,9 @@
         image_file = os.path.join(self._directory, image_url)
         return graph.to_latex(image_file) or ''
 
-    def write_class(self, out, doc):
+    def write_class(self, out, doc, short_name=None):
+        if short_name is None: short_name = doc.canonical_name[-1]
+        
         if self._list_classes_separately:
             self.write_header(out, doc)
         self.write_start_of(out, 'Class Description')
@@ -387,7 +374,7 @@
         else:
             seclevel = 1
             out(self.section('%s %s' % (self.doc_kind(doc),
-                                        _dotted(doc.canonical_name[-1])), 
+                                        _dotted(short_name)), 
                              seclevel, ref=doc))
 
         if ((doc.bases not in (UNKNOWN, None) and len(doc.bases) > 0) or
@@ -439,6 +426,18 @@
         # Mark the end of the class (for the index)
         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]))
+
     #////////////////////////////////////////////////////////////
     #{ Module hierarchy trees
     #////////////////////////////////////////////////////////////
@@ -1058,6 +1057,9 @@
         else:
             return 'Variable'
 
+    # [xx] list modules, classes, and functions as top-level index
+    # items.  Methods are listed under their classes.  Nested classes
+    # are listed under their classes.
     def indexterm(self, doc, pos='only'):
         """Mark a term or section for inclusion in the index."""
         if not self._index: return ''
@@ -1065,39 +1067,30 @@
             return ''
 
         pieces = []
-        
-        if isinstance(doc, ClassDoc):
-            classCrossRef = '\\index{\\EpydocIndex[%s]{%s}|see{%%s}}\n' \
-              % (self.doc_kind(doc).lower(), 
-                 _dotted('%s' % doc.canonical_name))
-        else:
-            classCrossRef = None
-
-        while isinstance(doc, ClassDoc) or isinstance(doc, RoutineDoc):
-            if doc.canonical_name == UNKNOWN:
-                return '' # Give up.
-            pieces.append('\\EpydocIndex[%s]{%s}' %
-                          (self.doc_kind(doc).lower(), 
-                           _dotted('%s' % doc.canonical_name)))
+        kinds = []
+        while True:
+            if doc.canonical_name in (None, UNKNOWN): return '' # Give up.
+            pieces.append(doc.canonical_name[-1])
+            kinds.append(self.doc_kind(doc).lower())
             doc = self.docindex.container(doc)
-            if doc == UNKNOWN:
-                return '' # Give up.
+            if isinstance(doc, ModuleDoc): break
+            if doc is None: break
+            if doc == UNKNOWN: return '' # give up.
 
         pieces.reverse()
-        if pos == 'only':
-            term = '\\index{%s}\n' % '!'.join(pieces)
-        elif pos == 'start':
-            term = '\\index{%s|(}\n' % '!'.join(pieces)
-        elif pos == 'end':
-            term = '\\index{%s|)}\n' % '!'.join(pieces)
-        else:
-            raise AssertionError('Bad index position %s' % pos)
+        kinds.reverse()
+        for i in range(1, len(pieces)):
+            pieces[i] = '%s.%s' % (pieces[i-1], pieces[i])
+        pieces = ['\\EpydocIndex{%s}{%s}{%s}' % (piece.lower(), piece, kind)
+                  for (piece, kind) in zip (pieces, kinds)]
+
+        if pos == 'only': modifier = ''
+        elif pos == 'start': modifier = '|('
+        elif pos == 'end': modifier = '|)'
+        else: raise AssertionError('Bad index position %s' % pos)
+
+        term = '\\index{%s%s}\n' % ('!'.join(pieces), modifier)
         
-        if pos in ['only', 'start'] and classCrossRef is not None:
-            term += classCrossRef % ('\\EpydocIndex[%s]{%s}' %
-                                     (self.doc_kind(doc).lower(), 
-                                      _dotted('%s'%doc.canonical_name)))
-            
         return term
 
     #: Map the Python encoding representation into mismatching LaTeX ones.

Modified: trunk/epydoc/src/epydoc/docwriter/latex_sty.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/latex_sty.py	2008-02-26 03:13:30 UTC (rev 1792)
+++ trunk/epydoc/src/epydoc/docwriter/latex_sty.py	2008-02-26 17:11:38 UTC (rev 1793)
@@ -41,30 +41,41 @@
 % $Id:$
 
 \NeedsTeXFormat{LaTeX2e}%
-\ProvidesClass{epydoc}[2007/04/06 v3.0beta1 Epydoc Python Documentation]
+\ProvidesClass{epydoc-base}[2008/02/26 v3.0.1 Epydoc Python Documentation]
 
 % ======================================================================
-% Basic Package Requirements
+% Options
 
-\RequirePackage{alltt, boxedminipage}
-\RequirePackage{multirow, amssymb}
-\RequirePackage[headings]{fullpage}
-\RequirePackage[usenames]{color}
+% These two packages are used to process options:
 \RequirePackage{ifthen}
+\RequirePackage{xkeyval}
 
-% ======================================================================
-% Options
-
+% Define an option 'index' that sets the boolean value \@doIndex
 \newif\if@doIndex
 \@doIndexfalse
-\DeclareOption{index}{\@doIndextrue}
+\DeclareOptionX{index}{\@doIndextrue}
 
+% Define an option 'hyperlink' that sets the boolean value \@docHyperlink
 \newif\if@doHyperlink
 \@doHyperlinkfalse
-\DeclareOption{hyperlink}{\@doHyperlinktrue}
+\DeclareOptionX{hyperlink}{\@doHyperlinktrue}
 
-\ProcessOptions\relax
+% Pass the 'title' & 'creator' options to the hyperref package.
+\DeclareOptionX{title}[]{\PassOptionsToPackage{pdftitle={#1}}{hyperref}}
+\DeclareOptionX{creator}[]{\PassOptionsToPackage{pdfcreator={#1}}{hyperref}}
 
+% Process the options list.
+\ProcessOptionsX\relax
+
+% ======================================================================
+% Package Requirements
+
+\RequirePackage{alltt, boxedminipage}
+\RequirePackage{multirow, amssymb}
+\RequirePackage[headings]{fullpage}
+\RequirePackage[usenames]{color}
+\RequirePackage{graphicx}
+
 \@ifclassloaded{memoir}{%
     \RequirePackage[other,notbib]{tocbibind}
 }{%
@@ -81,6 +92,17 @@
     \makeindex
 \fi
 
+\ifx\pdfoutput\undefined\newcommand{\driver}{dvips}
+\else\ifnum\pdfoutput=1\newcommand{\driver}{pdftex}
+\else\newcommand{\driver}{dvips}\fi\fi
+
+\RequirePackage[\driver, pagebackref, 
+    bookmarks=true, bookmarksopen=false, pdfpagemode=UseOutlines, 
+    colorlinks=true, linkcolor=black, anchorcolor=black, citecolor=black, 
+    filecolor=black, menucolor=black, pagecolor=black, urlcolor=UrlColor]
+    {hyperref}
+
+
 % ======================================================================
 % General Formatting
 
@@ -150,14 +172,16 @@
 % Index Terms
 
 % The \EpydocIndex command is used to mark items that should be included
-% in the index.  It takes one optional argument, specifying the 'kind'
-% of the object, and one required argument, the term that should be
-% included in the index.  (This command is used inside the \index
-% command.)  kind can be Package, Script, Module, Class, Class Method,
-% Static Method, Method, Function, or Variable.
-\newcommand{\EpydocIndex}[2][]{%
+% in the index.  It takes three arguments.  The first argument is the
+% item's case-normalized name; this is typically discarded, and is
+% simply used to ensure the proper (i.e., case-insensitive) sort order
+% in the index.  The second argument is the item's name; and the
+% third item is the item's "kind".  "kind" can be Package, Script, Module,
+% Class, Class Method, Static Method, Method, Function, or Variable.
+% This command is used inside of the \index{...} command.
+\newcommand{\EpydocIndex}[3]{%
     #2 %
-    \ifthenelse{\equal{#1}{}}{}{\textit{(\MakeLowercase{#1})}}}
+    \ifthenelse{\equal{#3}{}}{}{\textit{(#3)}}}
     
 % ======================================================================
 % Descriptions (docstring contents)
@@ -582,11 +606,15 @@
 %
 % $Id:$
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesClass{epydoc}[2007/04/06 v3.0beta1 Epydoc Python Documentation]
-\DeclareOption{index}{\PassOptionsToPackage{index}{epydoc-base}}
-\DeclareOption{hyperlink}{\PassOptionsToPackage{hyperlink}{epydoc-base}}
-\ProcessOptions\relax
+\ProvidesClass{epydoc-boxes}[2008/02/26 v3.0.1 Epydoc Python Documentation]
 
+\RequirePackage{xkeyval}
+\DeclareOptionX{index}{\PassOptionsToPackage{index}{epydoc-base}}
+\DeclareOptionX{hyperlink}{\PassOptionsToPackage{hyperlink}{epydoc-base}}
+\DeclareOptionX{title}[]{\PassOptionsToPackage{title={#1}}{epydoc-base}}
+\DeclareOptionX{creator}[]{\PassOptionsToPackage{creator={#1}}{epydoc-base}}
+\ProcessOptionsX\relax
+
 \RequirePackage{epydoc-base}
 \RequirePackage{longtable}
 
@@ -810,11 +838,15 @@
 %
 % $Id:$
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesClass{epydoc}[2007/04/06 v3.0beta1 Epydoc Python Documentation]
-\DeclareOption{index}{\PassOptionsToPackage{index}{epydoc-base}}
-\DeclareOption{hyperlink}{\PassOptionsToPackage{hyperlink}{epydoc-base}}
-\ProcessOptions\relax
+\ProvidesClass{epydoc-shaded}[2008/02/26 v3.0.1 Epydoc Python Documentation]
 
+\RequirePackage{xkeyval}
+\DeclareOptionX{index}{\PassOptionsToPackage{index}{epydoc-base}}
+\DeclareOptionX{hyperlink}{\PassOptionsToPackage{hyperlink}{epydoc-base}}
+\DeclareOptionX{title}[]{\PassOptionsToPackage{title={#1}}{epydoc-base}}
+\DeclareOptionX{creator}[]{\PassOptionsToPackage{creator={#1}}{epydoc-base}}
+\ProcessOptionsX\relax
+
 \RequirePackage{epydoc-base}
 
 \definecolor{gray95}{gray}{0.95}
@@ -1032,11 +1064,18 @@
 % how different pieces of the documentation are displayed.
 %
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesClass{epydoc}[2007/04/06 v3.0beta1 Epydoc Python Documentation]
-\DeclareOption{index}{\PassOptionsToPackage{index}{epydoc-base}}
-\DeclareOption{hyperlink}{\PassOptionsToPackage{hyperlink}{epydoc-base}}
-\ProcessOptions\relax
 
+% Replace 'XXX' with a new name:
+\ProvidesClass{epydoc-XXX}[2008/02/26 v3.0.1 Epydoc Python Documentation]
+
+% Pass options to the epydoc base package.
+\RequirePackage{xkeyval}
+\DeclareOptionX{index}{\PassOptionsToPackage{index}{epydoc-base}}
+\DeclareOptionX{hyperlink}{\PassOptionsToPackage{hyperlink}{epydoc-base}}
+\DeclareOptionX{title}[]{\PassOptionsToPackage{title={#1}}{epydoc-base}}
+\DeclareOptionX{creator}[]{\PassOptionsToPackage{creator={#1}}{epydoc-base}}
+\ProcessOptionsX\relax
+
 \RequirePackage{epydoc-base}
 
 % Add \renewcommand and \renewenvironment commands here.


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.