[Epydoc-commits] SF.net SVN: epydoc: [1739] trunk/epydoc/doc/epydoc-latex-demo.tex
Brought to you by:
edloper
Menu
▾
▴
[Epydoc-commits] SF.net SVN: epydoc: [1739] trunk/epydoc/doc/epydoc-latex-demo.tex
|
From: <ed...@us...> - 2008-02-23 01:59:28
|
Revision: 1739
http://epydoc.svn.sourceforge.net/epydoc/?rev=1739&view=rev
Author: edloper
Date: 2008-02-22 17:59:26 -0800 (Fri, 22 Feb 2008)
Log Message:
-----------
- A demonstration of the output generated by epydoc's latex writer
Added Paths:
-----------
trunk/epydoc/doc/epydoc-latex-demo.tex
Added: trunk/epydoc/doc/epydoc-latex-demo.tex
===================================================================
--- trunk/epydoc/doc/epydoc-latex-demo.tex (rev 0)
+++ trunk/epydoc/doc/epydoc-latex-demo.tex 2008-02-23 01:59:26 UTC (rev 1739)
@@ -0,0 +1,524 @@
+% epydoc -- Demo & description of latex writer output
+%
+% Copyright (C) 2008 Edward Loper
+% Author: Edward Loper <ed...@lo...>
+% URL: <http://epydoc.sf.net>
+%
+% $Id: apidoc.py 1729 2008-02-19 16:49:16Z edloper $
+
+% This is the basic preamble that's always included (in the api.tex file).
+% If any reStructuredText docstrings are used, then it is extended using
+% the preamble material used by reStructuredText.
+\documentclass{article}
+\usepackage[index]{epydoc}
+\usepackage[utf8]{inputenc}
+\definecolor{UrlColor}{rgb}{0,0.08,0.45}
+\usepackage[pdftex, pagebackref, pdftitle={API Documentation}, pdfcreator={epydoc 3.0.1}, bookmarks=true, bookmarksopen=false, pdfpagemode=UseOutlines, colorlinks=true, linkcolor=black, anchorcolor=black, citecolor=black, filecolor=black, menucolor=black, pagecolor=black, urlcolor=UrlColor]{hyperref}
+\begin{document}
+
+\title{Epydoc LaTeX Writer Output Demo}
+\author{}
+\date{}
+\maketitle
+
+This file provides a demonstration and description of epydoc's LaTeX
+output. Most of the important information is in the comments, so you
+should read this file in its original form (and not as a rendered pdf).
+By looking at this file, and at the epydoc-default.sty file, you should
+be able to determine how to write your own customized style file.
+
+% ======================================================================
+
+\section{General Formatting}
+
+\subsection{Hyperlinks and Crossreferences}
+
+% The \EpydocDottedName command is used to escape dotted names. In
+% particular, it escapes underscores (_) and allows non-hyphenated
+% wrapping at '.' separator characters.
+\EpydocDottedName{my_module.Zip}
+
+% The \EpydocHypertarget command is used to mark targets that hyperlinks
+% may point to. It takes two arguments: a target label, and text
+% contents. (In some cases, the text contents will be empty.) Target
+% labels are formed by replacing '.'s in the name with ':'s. The
+% default stylesheet creates a \label for the target label, and displays
+% the text.
+\EpydocHypertarget{foo:bar:baz}{\EpydocDottedName{foo.bar.baz}}
+
+% The \EpydocHyperlink command is used to create a link to a given target.
+% It takes two arguments: a target label, and text contents. The
+% default stylesheet just displays the text contents.
+\EpydocHyperlink{foo:bar:baz}{\EpydocDottedName{foo.bar.baz}}
+
+% The \CrossRef command creates a cross-reference to a given target,
+% including a pageref. It takes one argument, a target label.
+\CrossRef{foo:bar:baz}
+
+\subsection{Indexing}
+
+% 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.
+\index{\EpydocIndex[Script]{\EpydocDottedName{fooble}}}
+
+\subsection{Source Code Syntax Highlighting}
+
+% Doctest blocks are colorized using a variety of commands, all beginning
+% with the prefix "\pysrc". See epydoc-default.sty for a full list.
+\begin{alltt}
+\pysrcprompt{{\textgreater}{\textgreater}{\textgreater} }f(x)
+\pysrcoutput{123}\end{alltt}
+
+\subsection{reStructuredText Admonitions}
+
+% These would be defined by rst's style file:
+\newlength{\admonitionwidth}
+\setlength{\admonitionwidth}{.8\textwidth}
+
+% The reSTadmonition environment is used to display reStructuredText
+% admonitions, such as ``..warning::'' and ``..note::''. It takes
+% one optional argument, the admonition type.
+\begin{reSTadmonition}[note]
+ This is a note.
+\end{reSTadmonition}
+
+% ======================================================================
+
+% Each module is listed in its own section. (These sections are created
+% as separate files, and \include-ed into the main api.tex file). The
+% section contains:
+% - The module description (from the module's docstring)
+% - A metadata section (author, version, warnings, etc)
+% - A list of submodules (if it's a package)
+% - A list of classes defined by the module (only if the
+% --list-classes-separately option is used).
+% - A subsection describing the functions defined by the module.
+% - A subsection describing the variables defined by the module.
+% - A subsection for each class defined by the module (only if
+% the --list-classes-separately option is *not* used).
+\section{my\_module}
+
+ % The EpydocModuleDescription environment is used to mark the
+ % module's description (from its docstring)
+ \begin{EpydocModuleDescription}
+ This is an example module, used to demonstrate the LaTeX commands and
+ environments used by epydoc.
+ \end{EpydocModuleDescription}
+
+ % Each metadata item is listed separately. There are three environments
+ % and commands used for metadata:
+ % - The \EpydocMetadataSingleValue command is used to display a metadata
+ % field with a single value. It takes two arguments: the metadata
+ % field name and the metadata description.
+ % - The \EpydocMetadataShortList environment is used to display a
+ % metadata field with multiple values when the field declares that
+ % short=True; i.e., that multiple values should be combined into a
+ % single comma-delimited list. It takes one argument (the metadata
+ % field name); and items should be separated by the \and command.
+ % - The \EpydocMetadataLongList environment is used to display a
+ % metadata field with multiple values when the field declares that
+ % short=False; i.e., that multiple values should be listed
+ % separately in a bulleted list. It takes one argument (the metadata
+ % field name); and items should marked wit hthe \item command.
+ \EpydocMetadataSingleValue{See Also}{some reference.}
+
+ \begin{EpydocMetadataShortList}{Author}
+ joe \and mary
+ \end{EpydocMetadataShortList}
+
+ \begin{EpydocMetadataLongList}{Notes}
+ \item This is one note.
+ \item This is a second note.
+ \end{EpydocMetadataLongList}
+
+ % The list of submodules that a package contains is put it its own
+ % subsection. The list is displayed using the EpydocModuleList
+ % environment. Nested submodules are displayed using nested
+ % EpydocModuleList environments. If the modules are divided into
+ % groups (with the epydoc @group field), then groups are displayed
+ % using the \EpydocGroup command, followed by a nested EpydocModuleList.
+ \subsection{Submodules}
+ \begin{EpydocModuleList}
+ \item[\EpydocHyperlink{my_module:foo}{\EpydocDottedName{my_module.foo}}]
+ Description of my\_module.foo.
+ \item[\EpydocHyperlink{my_module:bar}{\EpydocDottedName{my_module.bar}}]
+ Description of my\_module.bar.
+ \begin{EpydocModuleList}
+ \item[\EpydocHyperlink{my_module:bar:soap}
+ {\EpydocDottedName{my_module.bar.soap}}]
+ Description of my\_module.bar.soap.
+ \end{EpydocModuleList}
+ \EpydocGroup{Some Group}
+ \begin{EpydocModuleList}
+ \item[\EpydocHyperlink{my_module:baz}
+ {\EpydocDottedName{my_module.baz}}]
+ Description of my\_module.baz.
+ \end{EpydocModuleList}
+ \end{EpydocModuleList}
+
+ % The list of classes that a module contains is just like the list
+ % of submodules that a package contains, except that the list
+ % environment EpydocClassList and the command \EpydocGroup
+ % are used. (Note that this list is only included when the
+ % --list-classes-separately option is used.)
+ \subsection{Classes}
+ \begin{EpydocClassList}
+ \item[\EpydocHyperlink{my_module:Zip}
+ {\EpydocDottedName{my_module.Zipasdkfjsdflsd}}]
+ Description of my\_module.Zip.
+ \item[\EpydocHyperlink{my_module:Zap}
+ {\EpydocDottedName{my_module.Zap}}]
+ Description of my\_module.Zap.
+ \EpydocGroup{Some Group}
+ \begin{EpydocClassList}
+ \item[\EpydocHyperlink{my_module:Zam}
+ {\EpydocDottedName{my_module.Zam}}]
+ Description of my\_module.Zam.
+ \item[\EpydocHyperlink{my_module:Zam}
+ {\EpydocDottedName{my_module.Zam}}]
+ Description of my\_module.Zam.
+ \end{EpydocClassList}
+ \end{EpydocClassList}
+
+ % The functions that a module contains are listed in a separate
+ % subsection. This subsection contains a single EpydocFunctionList
+ % environment
+ \subsection{Functions}
+
+ % The EpydocFunctionList environment is used to display functions.
+ % It contains one \EpydocFunction command for each function. This
+ % command takes 8 arguments:
+ %
+ % - The function's signature: an EpydocFunctionSignature environment
+ % specifying the signature for the function.
+ %
+ % - The function's description (from the docstring)
+ %
+ % - The function's parameters: An EpydocFunctionParameters list
+ % environment providing descriptions of the function's parameters.
+ % (from the epydoc @param, @arg, @kwarg, @vararg, @type fields)
+ %
+ % - The function's return description (from the epydoc @rerturns field)
+ %
+ % - The function's return type (from the epydoc @rtype field)
+ %
+ % - The function's exceptions: An EpydocFunctionRaises list
+ % environment describing exceptions that the function may raise
+ % (from the epydoc @raises field)
+ %
+ % - The function's override: An EpydocFunctionOverrides command
+ % describing the method that this function overrides (if any)
+ %
+ % - The function's metadata: Zero or more EpydocMetadata*
+ % commands/environments, taken from metadata fields (eg @author)
+ %
+ % All arguments except for the first (the signature) may be empty.
+ %
+ \begin{EpydocFunctionList}
+
+ \EpydocFunction{
+ % Argument 1: The function signature
+ %
+ % The EpydocFunctionSignature is used to display a function's
+ % signature. It expects one argument, the function's name. The
+ % body of the environment containd the parameter list. The
+ % following commands are used in the parameter list, to mark
+ % individual parameters:
+ % - \Param: Takes one required argument (the parameter name) and
+ % one optional argument (the defaultt value).
+ % - \VarArg: Takes one argument (the varargs parameter name)
+ % - \KWArg: Takes one argument (the keyword parameter name)
+ % - \GenericArg: Takes no arguments (this is used for '...', e.g.
+ % when the signature is unknown).
+ % - \TupleArg: Used inside of the \Param command, to mark
+ % argument tuples. Individual elements of the argument tuple
+ % are separated by the \and command.
+ %
+ % Parameters are separated by the \and command.
+ \begin{EpydocFunctionSignature}{myfunc}%
+ \Param{x}%
+ \and \Param{y}%
+ \and \Param{i}%
+ \and \Param{j}%
+ \and \Param{\TupleArg{a \and b}}%
+ \and \VarArg{rest}, \KWArg{keywords}%
+ \end{EpydocFunctionSignature}
+ }{
+ % Argument 2: The function description
+ This is an example function.
+ }{
+ % Argument 3: The function parameter descriptions
+ %
+ % The EpydocFunctionParameters list environment is used to
+ % describe the function's parameters. It takes a single
+ % required argument, a string which can be used to set the
+ % label width for the list. (I.e., this string is as long
+ % as the longest parameter name.) The list contains one
+ % \item for each parameter description. Parameter types
+ % are currently listed as part of the text (not using any
+ % special environments or commands)
+ \begin{EpydocFunctionParameters}{xxxxxxxx}
+ \item[x] Description of parameter x.
+
+ (type=int)
+
+ \item[i, j] Description of parameters x and y.
+
+ \item[keywords] Description of the keywords parameter.
+ \end{EpydocFunctionParameters}
+ }{
+ % Argument 4: The function return value description
+ description of the return value
+ }{
+ % Argument 5: The function return value tupe
+ int
+ }{
+ % Argument 6: The function exception descriptions
+ %
+ % The EpydocRaises list environment is used to display the
+ % list of exceptions that the function may raise. The list
+ % contains one \item for each exception.
+ \begin{EpydocFunctionRaises}
+ \item[ValueError] If there's some problem with a value.
+ \item[TypeError] If the wrong type is given.
+ \end{EpydocFunctionRaises}
+ }{
+ % Argument 7: The function overrides command
+ %
+ % (this is only used for methods, not functions)
+ }{
+ % Argument 8: The function metadta
+ %
+ % The metadata section uses the same commands that the module-
+ % level metadata section uses; see the discussion above.
+ \EpydocMetadataSingleValue{See Also}{some reference.}
+
+ \begin{EpydocMetadataShortList}{Author}
+ joe \and mary
+ \end{EpydocMetadataShortList}
+
+ \begin{EpydocMetadataLongList}{Notes}
+ \item This is one note.
+ \item This is a second note.
+ \end{EpydocMetadataLongList}
+ }
+
+ % If functions are divided into groups (with the epydoc @group
+ % field), then group headers are marked with the \EpydocGropu
+ % command.
+ \EpydocGroup{Some Group}
+
+ \EpydocFunction{
+ \begin{EpydocFunctionSignature}{\EpydocDottedName{some_func}}
+ \Param{x} \and \Param{y} \and \Param{z}
+ \end{EpydocFunctionSignature}}
+ {}{}{}{}{}{}{}
+
+ \end{EpydocFunctionList}
+
+ % The variables that a module contains are listed in a separate
+ % subsection. This section contains a single EpydocVariableList
+ % environment
+ \subsection{Variables}
+
+ % The EpydocVariableList environment is used to describe module
+ % variables. It contains one \EpydocVariable command for each
+ % variable. This command takes four required arguments:
+ %
+ % - The variable's name
+ % - The variable's description (from the docstring)
+ % - The variable's type (from the epydoc @type field)
+ % - The variable's value
+ %
+ % If any of these arguments is not available, then the empty
+ % string will be used.
+ %
+ % If the variables are divided into groups (with the epydoc @group
+ % field), then the \EpydocInternalHeader command is used to mark
+ % the beginning of each variable group.
+ \begin{EpydocVariableList}
+ \EpydocVariable{\EpydocHyperlink{my_module:gorp}
+ {\EpydocDottedName{my_module.gorp}}}
+ {Description of the variable gorp}
+ {int}
+ {12}
+ \EpydocVariable{\EpydocHyperlink{my_module:moo}
+ {\EpydocDottedName{my_module.moo}}}
+ {Description of the variable moo}
+ {str}
+ {'hello'}
+ \EpydocVariable{\EpydocHyperlink{my_module:cow}
+ {\EpydocDottedName{my_module.cow}}}
+ {} % no description
+ {} % no type
+ {} % no value
+ \end{EpydocVariableList}
+
+ % The remaineder of the module's section consists of one subsection
+ % for each class defined by the module. (However, if the
+ % --list-classes-separately option is used, then these subsections
+ % are not generated; instead, epydoc will generate a separate
+ % top-level section for each class.) Each class section contains:
+ % - The class's base tree (or a class tree graph, if the options
+ % "--graph classtree" or "--graph umlclasstree" are used).
+ % - A list of known subclasses.
+ % - The class description (from the class's docstring)
+ % - A metadata section (author, version, warnings, etc)
+ % - A list of methods defined by the class
+ % - A list of properties defined by the class
+ % - A list of class variables defined by the class
+ % - A list of instance variables defined by the class
+ \subsection{Class \EpydocDottedName{Zip}}
+
+ % The base tree is 'drawn' using a carefully constructed tabular
+ % environment. Here's an example of what it can look like:
+ \begin{tabular}{cccccc}
+ \multicolumn{2}{r}{
+ \settowidth{\EpydocBCL}{\EpydocDottedName{MyBaseClass}}
+ \multirow{2}{\EpydocBCL}{\EpydocHyperlink{object}
+ {\EpydocDottedName{MyBaseClass}}}}
+ && \\
+ \cline{3-3}
+ &&\multicolumn{1}{c|}{} && \\
+ &&\multicolumn{2}{l}{\textbf{\EpydocDottedName{my_module.Zip}}}
+ \end{tabular}
+
+ % The known subclasses are displayed using an \EpydocMetadataSingleValue
+ % command or an \EpydocMetadataShortList environment. See the
+ % description of these above (for module metadata).
+ \begin{EpydocMetadataShortList}{Known Subclasses}
+ \EpydocHyperlink{my_module:Zap}{\EpydocDottedName{my_module.zap}}
+ \and
+ \EpydocHyperlink{my_module:Zam}{\EpydocDottedName{my_module.zam}}
+ \end{EpydocMetadataShortList}
+
+ % The EpydocClassDescription environment is used to mark the
+ % class's description (from its docstring)
+ \begin{EpydocClassDescription}
+ This is an example class, used to demonstrate the LaTeX commands and
+ environments used by epydoc.
+ \end{EpydocClassDescription}
+
+ % The metadata section uses the same commands that the module-
+ % level metadata section uses; see the discussion above.
+ \EpydocMetadataSingleValue{See Also}{some reference.}
+
+ \begin{EpydocMetadataShortList}{Author}
+ joe \and mary
+ \end{EpydocMetadataShortList}
+
+ % The methods that a class defines are listed in a separate
+ % subsubsection. This subsubsection contains a single
+ % EpydocFunctionList environment.
+ \subsubsection{Methods}
+
+ % The EpydocFunction environment was described above (when it was
+ % used with module-level functions.) The only difference here is
+ % that functions may optionally include a command specifying
+ % what method is overridden by this method (\EpydocFunctionOverrides)
+ % as the seventh argument to the \EpydocFunction command.
+ \begin{EpydocFunctionList}
+ \EpydocFunction{
+ \begin{EpydocFunctionSignature}{mymethod}
+ \Param{x} \and \Param{y}
+ \end{EpydocFunctionSignature}}
+ {This is an example function.}
+ {}{}{}{}
+ {
+ % The \EpydocFunctionOverrides command specifies which method
+ % was overridden by this method. It comes just before the
+ % metadata section. It takes one optional argument, which will
+ % be "1" if documentation was inherited from the overridden
+ % method; and one required argument, containing the name of
+ % the overridden method.
+ \EpydocFunctionOverrides[1]{\EpydocHyperlink{MyBaseClass:mymethod}
+ {\EpydocDottedName{MyBaseClass.mymethod}}}
+ }{}
+ \end{EpydocFunctionList}
+
+ % The properties that a class defines are listed in a separate
+ % subsection. This section contains a single EpydocPropertyList
+ % environment.
+ \subsubsection{Properties}
+
+ % The EpydocPropertyList environment is used to describe class
+ % properties. It contains one \EpydocProperty command for each
+ % property. This command takes six required arguments:
+ %
+ % - The property's name
+ % - The property's description (from the docstring)
+ % - The property's type (from the epydoc @type field)
+ % - The property's fget function
+ % - The property's fset function
+ % - The property's fdel function
+ %
+ % If any of these arguments is not available, then the empty
+ % string will be used.
+ %
+ % If the properties are divided into groups (with the epydoc @group
+ % field), then the \EpydocInternalHeader command is used to mark
+ % the beginning of each property group.
+ %
+ % If any properties are inherited from a base class, and if
+ % --inheritance=listed (the default), then they will be listed
+ % after all the other properties, using the
+ % \EpydocInheritanceList command. This command will be used
+ % once for each base class that properties are inherited from.
+ % It takes two arguments: the name of the base class that the
+ % properties were inherited from, and a list of property names.
+ \begin{EpydocPropertyList}
+ \EpydocProperty{\EpydocHyperlink{my_module:Zip:duck}
+ {\EpydocDottedName{duck}}}
+ {Description of the property duck}
+ {int}
+ {\EpydocDottedName{get_dock}}
+ {\EpydocDottedName{set_dock}}
+ {\EpydocDottedName{del_dock}}
+ \EpydocInheritanceList{MyBaseClass}{goose, pig}
+ \end{EpydocPropertyList}
+
+ % The class variabless that a class defines are listed in a
+ % separate subsection. This section contains a single
+ % EpydocClassVariableList environment.
+ \subsubsection{Class Variables}
+
+ % The EpydocClassVariableList environment is used the same way as
+ % the EpydocVariableList environment (shown above), with one
+ % exception: if any variables are inherited from a base class,
+ % and if--inheritance=listed (the default), then they will be
+ % listed after all the other properties, using the
+ % \EpydocInheritanceList command. This command will be used
+ % once for each base class that variabless are inherited from.
+ % It takes two arguments: the name of the base class that the
+ % properties were inherited from, and a list of property names.
+ \begin{EpydocClassVariableList}
+ \EpydocVariable{\EpydocHyperlink{my_module:Zip:quack}
+ {\EpydocDottedName{my_module.Zip.quack}}}
+ {Description of the class variable quack}
+ {str} % type
+ {} % no value
+ \EpydocInheritanceList{MyBaseClass}{oink, bark}
+ \end{EpydocClassVariableList}
+
+ % The instance variabless that a instance defines are listed in a
+ % separate subsection. This section contains a single
+ % EpydocInstanceVariableList environment.
+ \subsubsection{Instance Variables}
+
+ % The EpydocInstanceVariableList environment is used the same
+ % way as the EpydocClassVariableList environment (shown above).
+ \begin{EpydocClassVariableList}
+ \EpydocVariable{\EpydocHyperlink{my_module:Zip:florp}
+ {\EpydocDottedName{my_module.Zip.flrop}}}
+ {Description of the class variable florp}
+ {list} % type
+ {} % no value
+ \EpydocInheritanceList{MyBaseClass}{blorp}
+ \end{EpydocClassVariableList}
+
+% That's all, folks!
+\end{document}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
