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_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 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 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 _pprint_var_value(self, s, maxwidth=100): if len(s) > maxwidth: s = s[:maxwidth - 3] + '...' if '\n' in s: return ('\\begin{alltt}\n%s\\end{alltt}' % plaintext_to_latex(s, nbsp=False, breakany=True)) else: return '{\\tt %s}' % plaintext_to_latex( s, nbsp=True, breakany=True)
def _pprint_var_value(self, s, maxwidth=100): if len(s) > maxwidth: s = s[:maxwidth-3] + '...' if '\n' in s: return ('\\begin{alltt}\n%s\\end{alltt}' % plaintext_to_latex(s, nbsp=False, breakany=True)) else: return '{\\tt %s}' % plaintext_to_latex(s, nbsp=True, breakany=True)
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{Nombre} & ") out("\\centering \\textbf{Descripción}& \\\\\n") out("\\cline{1-2}\n") out("\\endhead") out("\\cline{1-2}") out("\\multicolumn{3}{r}{\\small\\textit{") out("continúa en la página siguiente}}\\\\") 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. if grouped_inh_vars: for base in doc.mro(): if base in grouped_inh_vars: hdr = "Heredadas de %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.value, PropertyDoc): self.write_property_list_line(out, var_doc) else: self.write_var_list_line(out, var_doc) out("\\end{longtable}\n\n")
def func_arg(self, name, default): s = '\\textit{%s}' % plaintext_to_latex(self._arg_name(name)) if default is not None: if default.parse_repr is not UNKNOWN: s += '=\\texttt{%s}' % plaintext_to_latex(default.parse_repr) elif default.pyval_repr() is not UNKNOWN: s += '=\\texttt{%s}' % plaintext_to_latex(default.pyval_repr()) else: s += '=\\texttt{??}' return s
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{Nombre} & ') out('\\centering \\textbf{Descripción}& \\\\\n') out('\\cline{1-2}\n') out('\\endhead') out('\\cline{1-2}') out('\\multicolumn{3}{r}{\\small\\textit{') out('continúa en la página siguiente}}\\\\') 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. if grouped_inh_vars: for base in doc.mro(): if base in grouped_inh_vars: hdr = ('Heredadas de %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.value, PropertyDoc): self.write_property_list_line(out, var_doc) else: self.write_var_list_line(out, var_doc) out('\\end{longtable}\n\n')
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
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(self, out, doc): if self._list_classes_separately: self.write_header(out, doc) self.write_start_of(out, 'Descripción de la clase') # 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, 'Clases descendientes', 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, 'Métodos', doc, 'method', seclevel + 1) self.write_var_list(out, 'Propiedades', doc, 'property', seclevel + 1) self.write_var_list(out, 'Variables de clase', doc, 'classvariable', seclevel+1) self.write_var_list(out, 'Variables de instancia', doc, 'instancevariable', seclevel+1) # Mark the end of the class (for the index) out(self.indexterm(doc, 'end'))
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_repr = (var_doc.value not in (None, UNKNOWN) and (var_doc.value.parse_repr is not UNKNOWN or var_doc.value.pyval_repr() is not UNKNOWN)) if has_descr or has_type: out('\\raggedright ') if has_descr: out(self.docstring_to_latex(var_doc.descr, 10).strip()) if has_type or has_repr: out('\n\n') if has_repr: out('\\textbf{Value:} \n') pyval_repr = var_doc.value.pyval_repr() if pyval_repr is not UNKNOWN: out(self._pprint_var_value(pyval_repr, 80)) elif var_doc.value.parse_repr is not UNKNOWN: out(self._pprint_var_value(var_doc.value.parse_repr, 80)) if has_type: ptype = self.docstring_to_latex(var_doc.type_descr, 12).strip() out('%s\\textit{(type=%s)}' % (' '*12, ptype)) out('&\\\\\n') out('\\cline{1-2}\n')
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 _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
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 = "Heredados de %s" % plaintext_to_latex("%s" % self._base_name(base)) if self._crossref and base in self.class_set: hdr += " \\textit{(Sección \\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_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_repr = (var_doc.value not in (None, UNKNOWN) and (var_doc.value.parse_repr is not UNKNOWN or var_doc.value.pyval_repr() is not UNKNOWN)) if has_descr or has_type: out('\\raggedright ') if has_descr: out(self.docstring_to_latex(var_doc.descr, 10).strip()) if has_type or has_repr: out('\n\n') if has_repr: out('\\textbf{Value:} \n') pyval_repr = var_doc.value.pyval_repr() if pyval_repr is not UNKNOWN: out(self._pprint_var_value(pyval_repr, 80)) elif var_doc.value.parse_repr is not UNKNOWN: out(self._pprint_var_value(var_doc.value.parse_repr, 80)) if has_type: ptype = self.docstring_to_latex(var_doc.type_descr, 12).strip() out('%s\\textit{(type=%s)}' % (' ' * 12, ptype)) out('&\\\\\n') out('\\cline{1-2}\n')
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 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 visit_title_reference(self, node): m = _TARGET_RE.match(node.astext()) if m: text, target = m.groups() else: target = text = node.astext() text = plaintext_to_latex(text) xref = self._linker.translate_identifier_xref(target, text) self.body.append(xref) raise SkipNode()
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_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 = "Heredadas de %s" % plaintext_to_latex("%s" % self._base_name(base)) if self._crossref and base in self.class_set: hdr += " \\textit{(Sección \\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_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)))
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_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_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_module_tree_item(self, out, doc, depth=0): 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{(Sección~\\ref{%s}' % self.label(doc)) out(', página~\\pageref{%s})}\n\n' % self.label(doc)) if doc.submodules != UNKNOWN and doc.submodules: out(' ' * depth + ' \\begin{itemize}\n') for submodule in doc.submodules: self.write_module_tree_item(out, submodule, depth+4) out(' ' * depth + ' \\end{itemize}\n')
def write_module_tree_item(self, out, doc, depth=0): 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{(Sección~\\ref{%s}' % self.label(doc)) out(', página~\\pageref{%s})}\n\n' % self.label(doc)) if doc.submodules != UNKNOWN and doc.submodules: out(' ' * depth + ' \\begin{itemize}\n') for submodule in doc.submodules: self.write_module_tree_item(out, submodule, depth + 4) out(' ' * depth + ' \\end{itemize}\n')
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)) out('\\begin{longtable}') out('{|p{.30\\textwidth}|') out('p{.62\\textwidth}|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') for name, var_docs in groups: if name: out('\\multicolumn{2}{|l|}{') out('\\textbf{%s}}\\\\\n' % name) out('\\cline{1-2}\n') for var_doc in var_docs: if isinstance(var_doc, PropertyDoc): self.write_property_list_line(out, var_doc) else: self.write_var_list_line(out, var_doc) # [xx] deal with inherited methods better???? #if (self._inheritance == 'listed' and # isinstance(container, ClassDoc)): # out(self._inheritance_list(group, container.uid())) out('\\end{longtable}\n\n')
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)) out('\\begin{longtable}') out('{|p{.30\\textwidth}|') out('p{.62\\textwidth}|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') for name, var_docs in groups: if name: out('\\multicolumn{2}{|l|}{') out('\\textbf{%s}}\\\\\n' % name) out('\\cline{1-2}\n') for var_doc in var_docs: if isinstance(var_doc, PropertyDoc): self.write_property_list_line(out, var_doc) else: self.write_var_list_line(out, var_doc) # [xx] deal with inherited methods better???? #if (self._inheritance == 'listed' and # isinstance(container, ClassDoc)): # out(self._inheritance_list(group, container.uid())) out('\\end{longtable}\n\n')
def to_latex(self, docstring_linker, **options): """ Translate this docstring to LaTeX. @param docstring_linker: A LaTeX translator for crossreference links into and out of the docstring. @type docstring_linker: L{DocstringLinker} @param options: Any extra options for the output. Unknown options are ignored. @return: A LaTeX fragment that encodes this docstring. @rtype: C{string} """ # Default behavior: plaintext = plaintext_to_latex(self.to_plaintext(docstring_linker)) return '\\begin{alltt}\n%s\\end{alltt}\n\n' % plaintext
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')
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\\textit{(type=%s)}' % (' '*12, ptype)) # [xx] List the fget/fset/fdel functions? out('&\\\\\n') out('\\cline{1-2}\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')
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')
def write_func_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)) for name, var_docs in groups: if name: out('\n%s\\large{%s}\n' % (self.HRULE, name)) for var_doc in var_docs: self.write_func_list_box(out, var_doc)
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_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\\textit{(type=%s)}' % (' '*12, ptype)) out('&\\\\\n') out('\\cline{1-2}\n')
def write_func_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)) for name, var_docs in groups: if name: out('\n%s\\large{%s}\n' % (self.HRULE, name)) for var_doc in var_docs: self.write_func_list_box(out, var_doc)
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 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 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}{-1ex}\n') out('\\tableofcontents\n') out('\\addtolength{\\parskip}{1ex}\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 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 to_latex(self, docstring_linker, **options): if options.get('verbatim', self._verbatim) == 0: return plaintext_to_latex(self.to_plaintext(docstring_linker)) else: return ParsedDocstring.to_latex(self, docstring_linker, **options)
def sectionstar(self, title, depth): sec = self.STARSECTIONS[depth + self._top_section] return (('%s\n\n' % sec) % plaintext_to_latex(title))
def markup(self, s, tag): if tag == 'other': return plaintext_to_latex(s) else: return '\\pysrc%s{%s}' % (tag, plaintext_to_latex(s))
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 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 sectionstar(self, title, depth): sec = self.STARSECTIONS[depth+self._top_section] return (('%s\n\n' % sec) % plaintext_to_latex(title))
def func_arg(self, name, default): s = '\\textit{%s}' % plaintext_to_latex(self._arg_name(name)) if default is not None: s += '=\\texttt{%s}' % default.summary_pyval_repr().to_latex(None) return s
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(' \\begin{boxedminipage}{\\textwidth}\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 if func_doc.descr not in (None, UNKNOWN): out(self.docstring_to_latex(func_doc.descr, 4)) out(' \\vspace{1ex}\n\n') # Parameters 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(' '*6+'\\begin{quote}\n') out(' \\begin{Ventry}{%s}\n\n' % (longest*'x')) # Params that have @type but not @param info: unseen_types = set(func_doc.arg_types) # List everything that has a @param: for (arg_names, arg_descr) in func_doc.arg_descrs: arg_name = plaintext_to_latex(', '.join(arg_names)) out('%s\\item[%s]\n\n' % (' '*10, arg_name)) 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\\textit{(%s=%s)}\n\n' % (' '*12, lhs, rhs)) out(' \\end{Ventry}\n\n') out(' '*6+'\\end{quote}\n\n') out(' \\vspace{1ex}\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(' '*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+'\\textit{(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') out(' \\vspace{1ex}\n\n') # Raises if func_doc.exception_descrs not in (None, UNKNOWN, [], ()): out(' '*6+'\\textbf{Raises}\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') out(' \\vspace{1ex}\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')