mirror of
https://gitflic.ru/project/openide/openide.git
synced 2025-12-16 22:51:17 +07:00
1188 lines
47 KiB
Python
1188 lines
47 KiB
Python
#
|
|
# 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)
|