Contents
<<<< >>>>

Module: pymanual

Module and program to extract documentation strings from modules and transform them into documents of various formats. These formats are currently:

HTB: A zipped directory of HTML files and files on content and index which are also understood by Microsofts help compiler. Refer to the wxWidgets project for information on the HTB-format and available viewers at www.wxWidgets.org.
PDF: Adobe's portable document format.
HTML: A directory of the same files that are used to compile an HTB document.
TEX: A LaTeX source file that may be used to compile DVI and PDF documents using the well known LaTeX word processor.

This document is a formatted version of the documentation strings in the pymanual module.

This file may be either used as a program or as an imported module.

When used as a program, the synopsis is

for producing a hyper text book (HTB, refer to the wxWidgets for viewers and class FormatterHTB ): pymanual.py {module_names}
for producing HTML files (refer also to FormatterHTB ): pymanual.py --html [-p LaTeX_preamble] [--preamble LaTeX_preamble] {module_names}
for producing PDF (refer also to FormatterLaTeX ): pymanual.py --pdf [-p LaTeX_preamble] [--preamble LaTeX_preamble] {module_names} Please note that this requires the programs pdflatex and makeindex , common parts of most distributions of the LaTeX word processor, to be in the current paths where executables are searched. For details on the LaTeX_preamble refer to class FormatterLaTeX .
for producing LaTeX sources (refer also to FormatterLaTeX ): pymanual.py --tex [-p LaTeX_preamble] [--preamble LaTeX_preamble] {module_names}

where

LaTeX preamble:: This is an optional name of a file containing definitions to be pasted into the preamble of the produced LaTeX-file. Refer to class FormatterLaTeX .
module name:: This is a sequence of module names specifying the modules to be documented by the resulting document.

In case of producing a documentation of a single module, the output will be written into a file or directory whose base name will be the name of the module completed by a suffix describing the type of the document. As example consider the production of a documentation for this module:

pymanual.py pymanual produces a file pymanual.htb .
pymanual.py --html pymanual produces a directory pymanual containing HTML files (among others).
pamanual.py --pdf pymanual produces a file pymanual.pdf . This required pdflatex to be in the execution path.
pamanual.py --tex pymanual produces a file pymanual.tex .

In case of collecting the documentation of more than one module into one document, the base name of the resulting document is refman completed by an appropriate suffix.

For usage as an imported module refer to the functions pymanual_latex and pymanual_htb .

State Of Implementetion

As indicated by the version identifier, the current version of pymanual.py can be considered as a fairy complete but weakly tested implementation. The major test case has been the documentation of the program itself.

Motivation

Professionally, I use the programming languages C/C++, C# and JAVA. On these programming languages, the tool doxygen is available for in-source-documentation. Being able to produce comprehensible documentation of classes and functions directly within the source code proved to be extremely valuable.

In the specification phase, motivation and specification of a design can be attached to declarations of classes and functions before implementation. However, this can also be achieved by producing extra documents for specification. Nevertheless, in-source-documentation eases maintenance of this information in order to keep it useful.
In-source-documentation proved to ease maintenance and extension of implementations:
- A maintained specification of classes and functions adds the necessary redundancy to decide which implementation caused an erroneous behaviour of the implemented system: Is there an implementation fault in a particular method of a function or has it been used mistakenly?
- A comprehensible specification also serves as a manual and eases code reusing.

Python attaches documentation strings to each class, function, and method to serve mainly as a manual for using it. Documentation strings can be used quite like man-pages on UNIX systems and program pydoc produces manuals in HTML from these strings. Unfortunately, even manuals produced by pydoc are simple presentations of plain text lacking even simple text structures like sections and item lists. Python code can hardly be separated from free text. Following references to related implementations (other classes or functions) is not supported by hyperlinks.

pymanual.py is yet another approach to extend the usability of documentation strings. The program recognizes each occurance of a function name or a class name and produces hyperlinks to the corresponding documentation. pymanual.py allows the specification of section, item lists, enumerations, and description lists. Inlined code fragments may be highlighted. The program also recognizes parts of the documentation string that obviously have been added for use by module doctest .

pymanual does not produce any diagrams but

documentations of classes contain a synopsis section providing hyperlinks to inherited and inheriting classes, and
documentations of class methods contain a synopsis section on signature and occurances of methods of similar names in other documented classes. The latter feature has been added to reflect the fact that python does not use strong types. From a software refactorers view, each implemented method is similar to an interface in JAVA or C#. An object's ability to serve as an argument of a method or function depends exclusively on the availablity of the required methods and member variables (in contrast to type compatibility in strongly typed languages). So, hyperlinks from method A to methods of equal name provide a strong hint to recognize classes of objects that may be used in the same role as implementors of A.

Modules, classes, and funtions providing pymanual documentation may also specifiy some limited degree of meta information on authors, version, and copyright that will be displayed in the documentaton ^(cf.) However, like pydoc this program requires the imported modules to be compilable (since modules to be documented will be imported before producing any ouput).

Formatting Text

Text formatting with pymanual.py aims mainly at achieving two goals:

Availability of the same opportunities for structuring texts as they are available in books plus the option to inline Python source code plus the option to present lines of code, either to be processed by module doctest or not.
Documentation shall also be comprehensible from the plain text source. So, the task of documenting items by use of pymanual.py results in at least two documents:
1. One document in PDF or HTB providing a rich set of opportunities for structuring and highlighting text.
2. A plain text document to be processed by pydoc or the internal help command using only the original line breaks as text layout.

For achieving both goals, pymanual.py rather uses wikipedia like short formatting characters to describe the text format of a text item than using markup tags like in HTML etc. To restrict the effect of missing closings of formatting tags (and for the sake of easier implementation), tags are only valid within the same line of the documentation source (the __doc__ string).

Structering Texts

Linebreaks in the original plain text will not break lines in the richly formatted documentation. As an exception of this general rule, empty lines introduce new text paragraphs in the richly formatted documentation.

Use the lower than (<) and the larger than characters to embrace a single word that shall be highlighted as a code fragment (a file, class or function name). Use two lower than and greater than characters to embrace code fragments containing more than one word within the same line of the plain text source of the documentation. Note, that names of also documented modules, classes, and functions will recognized by the system. So, embracing such words is optional but recommended, to enhance comprehensibleness of the plain text. Inlined code fragments are usually presented in bold letters. Inlined code fragments are often printed in true type letters. However, using bold letters instead results into a much more harmonic text layout.

Analogously, "<!" and "!>" might be used to embrace emphasized text passages. These passages are usually printed in italics.

pymanual supports item lists, enumerations, and description lists. Use the star (*) to introduce an item of an item list as the first character of a new line in the original plain text. The double cross (#) specifies a new item of an enumeration. To specify a new item in a description list, type the name of the description (a single word) followed by a colon (:). If the name of the description consists of more than one word, use the underscore (_) as separator. The rest of the line in the plain text is considered to hold text describing the item. If the next lines start with a colon, they will also be added to the description of the item.

Each item may contain additional item lists, enumerations, or description lists. To start an encapsulated item list, start the line in the plain text source with a colon directly followed by s start (:*). Use ":#" to start a new enumeration or "item_name:" to start a description list start with a description on "item name".

Example:

an item covering two lines in the original plain text documentation.
1. encapsulated enumeration item 1.
2. encapsulated enumeration item 2.
description item2:
This is a part of the item list.

description item3:: This is indention level 0.
description item4:: This also.

Plain text source of the example:

<!Example:!>
* an <<item>>
: <<covering two lines>> in the original plain text documentation.
:# encapsulated enumeration item 1.
:# encapsulated enumeration item 2.
::description_item1: This is a part of the enumeration.
:description_item2: This is a part of the item list.
description_item3: This is indention level 0.
description_item4: This also.

Long Code Fragments And Preformatted Text

In addition to inlined code fragments that typically consist of single program symbols or short expressions, program documentations usually contain longer code fragments to present source code examples or preformatted text to show for instance text examples for configuration files etc.

Preformatted Text

 This is some preformatted text.
      The content is presented in true type letters.
    Preceed each line containing preformatted text with a bar '|'.

Original plain text of the example above:

| This is some preformatted text.
|      The content is presented in true type letters.
|    Preceed each line containing preformatted text with a bar '|'.

Python Source Code

Source code occurs in Python documentations for two purposes:

Present source code examples, and
input for the doctest module.

pymanual.py supports both by a special mode you can turn on typing a Python prompt as the first non-blank characters of a line in the plain documentation. This mode is the only one that spans over more than one line and has to be left by an empty line. Example:

>>> 2+2 # a Python expression 4 >>> # in this mode you have to provide the result of an expression >>> # since module doctest looks for prompts in the documentation >>> # an will report errors if results are missing. >>> context=FormattingContext(pymanual) >>> # names of modules, classes, functions, and methods will also be >>> # recognized in this mode. >>> >>> # leave this mode by an empty line in the plain text documentation.

In plain text, this example looks as follows:

 >>> 2+2 # a Python expression
 4
 >>> # in this mode you have to provide the result of an expression
 >>> # since module doctest looks for prompts in the documentation
 >>> # and will report errors if results are missing.
 >>> context=FormattingContext(pymanual)
 >>> # names of modules, classes, functions, and methods will also be
 >>> # recognized in this mode.
 >>>
 >>> # leave this mode by an empty line in the plain text documentation.

If you intend to use doctest , you may want to present code snippets that you do not want to be evaluated by doctest . In such cases you should use "|>>" instead of the standard Python prompt ">>>". This keyword will result into exactly the same formatted documentation but will be ignored by doctest .

|>> 2+2 # a simple Python expression 5 |>> # the example above presents an obvously wrong result. however, |>> # it will not be tested anyway. |>> pymanual_htb(['pymanual'], '.','HTB', FormatterHTB.m_englishPattern, FormatterHTB.m_englishTexts, FormatterHTB.m_englishTitle []) |>> # modules, functions, and classes will also be recognized in this mode.

Sectioning, Referencing, Indexing

Longer texts (like this one) should be organized in sections. pymanual.py supports three levels of sections. Embrace the headline of a section in the plain text documentation with " == ", " == = ", or " == == " to start a new section. For instance, the headline of this section has been produced by

=== Sectioning, Referencing, Indexing ===

Please note, that this three levels have to be mapped to sectioning levels provided by the used rich format. For instance, in LaTeX documents level, " == = " on modules is a subsubsection and on methods it is a paragraph .

A documentation may contain cross references to sections within the same documentation string. Therefore, a label has to be attached to a section. Labels are strings composed of letters and numbers serving as an identifier for a section. For instance, this section has the label refs . This label has been defined in the headline:

refs:=== Sectioning, Referencing, Indexing ===

Now, each text within this documentation string may refer to this section ^(cf.) using the markup tag :ref[refs] . Please refer to ^(cf.) for current limitations of tags in pymanual.py in general and limitations of the ref markup tag in particular.

For the sake of comprehensibleness of the plain text documentation, pymanual.py provides only few tags, in fact only two. The other one is for producing a hierarchical index. pymanual.py produces an hierarchical index on modules, classes, functions, and methods automatically. However, documentation on source code may introduce additional notation for instance on domain concepts that should be listed in the index. This can be achieved by use of tag index . This paragraph contains the tag :index[index|example] . As a consequence, the hierarchical index of this document comprises the key word "index" with aspect "example" associated with a link to this paragraph.

Meta information

pymanual.py analyses three sources of information. Two of these sources have been the issue of the previous sections.

information on classes, methods, and functions as provided by the reflective libraries of Python.
documentation strings as attached to modules, classes, methods, and functions.

Additionally, pymanual.py searches the main dictionary of modules, classes, methods, and functions for the attributes __author__ , __copyright__ , and __version__ . The data associated with these attributes will be presented in the documentation depending on the produced format of the richly formatted document.

Information on author, copyright, and version is inherited as usual in Python. Usually, information on these topics will only be presented if it changes. For instance in this file, only the pymanual module provides information on author, copyright, and version. So, this information will not be listed for functions and classes.

__author__ may be associated with a string describing the author of the documented entity. For instance, module pymanual defines the author "Dr. Harald Meyer auf'm Hofe, Kaiserslautern, Germany".
__copyright__ may be associated with a string describing information on the copyright. For instance, module pymanual defines the copyright "(c ) Dr. Harald Meyer auf'm Hofe 2005-2006".
__version__ may be associated with arbitrary data whith <str( )> producing an informative representation. Module pymanual defines its version by float 0.999 .

Known Bugs

Problems with tags index and ref : do not miss introducing blank.
Problems with tag ref : Works in HTB mode currently only within the same context. Probably this problem will be fixed somewhere in the future introducing a longref tag that also receives the target context as an argument. The system does not test whether the target of a reference actually exists. So, it produces blind references without warning. This is due to the fact that the design of this program strictly follows a single pass approach. It does not produce any tables for references and labels to ensure consistency.
Insertion in style codeline (mode for doctest): Inserting blanks will be inserted before the ... prompt.

History

0.999 Mai 2006: Fixes. Access to member attributes by getattr( ). Better support for directly imported classes.
0.99 Feb. 2006: Version with HTB and LaTeX output. Some error fixes on argspec interpretation etc.
0.9 Dec. 2005: Intial version with PDF and LaTeX output

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA