[table of contents] [master index] [functions] [scripts] [methods] [modules] [classes]
MODULE
GDoc - Generic documentation tool
PURPOSE
GDoc is designed to extract multi-line documentation strings from
programs or other text files, and output them formatted documentation.
Currently, the program can produce a set of hyperlinked html files,
a single latex document, or (for storage) xml documents.
FORMAT
GDoc extracts documentation "Items", which are usually header blocks
written above functions or variables, and outputs these as formatted
documentation. Each documentation item contains a series of sections,
each of which contains a heading on a line by itself (e.g., "PURPOSE",
"ARGUMENTS", etc.) followed by one or more lines of text. To provide
an example, the source code for the GDoc module is itself formatted
with header blocks in the required formate.
Items:
GDoc recognizes the beginnning and end of each documentation
Item by using the Python regular expression engine to search for
beginning and ending marker lines. Examples of such marker lines
are show below:
beginning marker: "#****c parent/name" , or
"#****ic parent/name"
ending marker "#***"
Here # is an example of a comment character that is used to mark the
beginning of a one line comment or remark in the language used in the
source code (e.g., ! in Fortran 90). The 4 asterisks in the beginning
marker line and the 3 asterisks in the ending marker are literal and
are required. The "c" following the asterisks in the first beginning
marker is an example of a single character code used to indicate the
type of object being documented (e.g., "c" for class, "f" for function,
etc.) in a user defined dictionary. The optional "i" character in the
second example of a beginning marker is used to indicate that the
item is an "internal" (or private) item. The string "name" in the above
denotes the name of the documentation Item, which is typically the name
of the variable, function, or other thing that is being documented.
GDoc searches for instances of Item names to create hyperlinks in html
documentation. The string "parent" in the above is the name of
another documentation Item that is the parent of this one in a hierarchy:
For example, a module may be the parent of a variable or procedure, and
a class may be the parent of its data attributes and/or methods. These
parent/child relationships are used to create a hierarchical tables of
contents for each source file (in multi-file html documentation) and
for the entire document (in both html or latex documentation).
Sections:
Each documentation item contains a list of Sections, each
of which begins with a heading, such "NAME" or "PURPOSE", on a line
by itself, followed by one or more lines of text. The user must
provide supply a list of recognized Section headings in the
configuration file, as discussed below.
Configuration:
Before parsing the source files, GDoc reads a configuration
file. The configuration file must specify, among other things:
i) The comment character that appears at the beginning of
begining and ending marker lines, and at the beginning of each
line of documentation (e.g, '#' in the above examples and in
the source code of the GDoc module).
ii) A list of names of the types of items to document (e.g.,
"module", "function", "variable", etc.), and an associated
single character codes for each. These (key : value) pairs
are stored in a user defined dictionary, e.g.,
("m":"module", # "f":"function", "v":"variable" , ... ).
iii)A list of recognized section headings (e.g., "NAME", "PURPOSE",
etc.).
The format of the configuration file is discussed in detail in the
documentation for function read_config. Examples of working
configuration files for generating the hmtl and latex documentation
for GDoc itself are given in the html.rc and latex.rc files,
respectively.
USAGE
To execute GDoc in Unix or Linux:
1) Change directory to a directory one level above the directory
containing the source file source, and the directory in which you
intend to create documentation. Make the documentation directory,
if it does not already exist, and create a configuration file.
2) Start the python interpreter by typing "python" at the shell
prompt. Within the interpreter, type "import GDoc". Then, enter
the name of the configuration file (relative to the current
directory) when prompted to do so. The GDoc directory must either
be in the PYTHONPATH environment variable or a subdirectory of a
directory in PYTHONPATH in order for python to find the module.
To execute GDoc in MS Windows, one may either:
1) Start up the python interpreter and "import GDoc", as in
unix. This requires that python search path be set so that it
can find the GDoc directory.
2) Double click on the GDoc/GDoc.py file, which should look
like a snake. This, however, makes the GDoc directory the
current directory, and thus requires that the source and
documentation directory be specified in the configuration file
either as as absolute paths or as paths relative to the GDoc
directory.
CLASS
Section
PURPOSE
Contains one Section within an Item of documentation. Each
Section contains a heading (e.g., 'FUNCTION', 'PURPOSE', etc.)
and the corresponding text.
CLASS ATTRIBUTES
types = list of recognized heading strings, e.g.,
Section.types = ('FUNCTION','PURPOSE',..)
ignore = list of Section types to exclude from documentation
INSTANCE ATTRIBUTES
heading = heading string (must be in list Section.types)
text = list of strings, each one line with '\n' stripped
METHODS
__init__([heading],[text]) - constructor
write(format,namespace) - returns string representation
in format = 'html' or 'xml'
METHOD
Section.write(format,namespace)
PURPOSE
Output one documentation Section as a string
ARGUMENTS
format - output format ('html' or 'xml')
namespace - dictionary of Items accessed by name.
Used to hyperlink html output
RETURN
string representation of item in chosen output format
If format == 'html', result is hyper-linked using namespace
If Section.type is in Section.ignore, returns blank string
CLASS
Item
PURPOSE
Each Item object contains the documentation for one
module, variable, function, class, etc.
CLASS ATTRIBUTES
types = Dictionary of allowed Item types,
keys are user defined one-character strings
values are strings, e.g., FUNCTION, VARIABLE, etc.
current = Item currently being processed
INSTANCE ATTRIBUTES
name = name (string)
type = type of object (string)
parent = parent (Item object)
access = 'public' or 'private' (string)
SrcFile = file from which it was extracted (SrcFile object)
pattern = regular expression object for name
Sections= list of Section objects
METHODS
__init__([attributes]) - constructor, all attributes optional
read(lines,i,n) - extract documentation for Item from source
write(format,namespace) - returns string representation in 'format'
html_ref(ext,target) - returns hyper-link to self
html_link(line,namespace) - returns line with self.names replaced
by href links
METHOD
Item.read(lines,i,n)
PURPOSE
Read one documentation Item object from a list of text lines
ARGUMENTS
lines - list of text line strings
i - # of current line
n - total # of strings in lines
RETURN
i - current line, from which to begin reading next Item
METHOD
Item.write(format,namespace,Doc_access,recursive)
PURPOSE
Output one documentation item as a string
ARGUMENTS
format - output format ('html', 'tex', or 'xml')
namespace - dictionary of Items accessed by name.
Used to hyperlink html output
Doc_access- 'public' -> write only if public Items,
'private' -> write public or private
RETURN
string representation of item in chosen output format
If format == 'html', result is hyper-linked using namespace
METHOD
Item.html_ref([ext],[target])
PURPOSE
Returns string containing html element Item.name
with an html href attribute linking to anchor of Item
ARGUMENTS
ext = if present, appends 'ext' string to filename in href.
Used to distinguish html documentation and html source
target = if present, adds target attribute to href.
Used to create new Browswer window
METHOD
Item.html_link(line)
RETURN
string line with instances of self.name replaced by html
self.name hyperlinks to self. Uses method html_ref
METHOD
Item.set_depth(depth)
PURPOSE
Sets depth attribute of self and all of its descendants.
METHOD
Item.html_toc()
PURPOSE
Returns string containing an html table of contents list item
for self, and a nested list containing its children, if any.
The method is applied recursively to children to generate a
table of contents for the tree of Items rooted at self.
CLASS
SrcFile - documentation extracted from a source file
CLASS ATTRIBUTES
current = current SrcFile
INSTANCE ATTRIBUTES
name = SrcFile name (in format used for output file names)
Items = list of Item objects
METHOD
SrcFile.read(file,namespace)
PURPOSE
Extract documentation Items from an entire file
ARGUMENTS
file - file object
namespace - namespace dictionary to which Items are added
RETURN
lines - Full text of input source file, with minimal
hyper-text anchors inserted for documented items
METHOD
SrcFile.write(format,namespace,Doc_access)
PURPOSE
Output documentation for instance SrcFile
ARGUMENTS
format - output format ('html' or 'xml')
namespace - dictionary of Items accessed by name.
Used to hyperlink html output
Doc_access- 'public' -> write only if public Items,
'private' -> write public or private
RETURN
string representation of SrcFile in chosen output format
If format == 'html', output is hyper-linked using namespace
CLASS
Document - documentation for an entire program or project
INSTANCE ATTRIBUTES
src_dir = path name for source directory
doc_dir = path name for documentation directory
filenames = list of file names of source files in src_dir
format = format of documentation, 'html' or 'xml'
access = 'public' (public Items only) or 'private' (private also)
SrcFiles = list of SrcFile objects, in same order as filenames
namespace = dictionary of Item objects accessed by name
indices = dictionary of lists of items, used to create indices.
Keys are type name, or "master" for master index.
root = string identifier for "parent" of top level Items
METHODS
read() - read source files in self.filenames from self.src_dir
make_indices() - make master indices and
make_tree() - finds parents of each Item, thus creating a tree
html_index(key,columns) - returns html table of self.indices[key]
index_links() - return string with hyperlinks to toc and indices
write() - write documentation to files in self.doc_dir
METHOD
Document.read()
PURPOSE
Extract documentation for a multi-file Document
METHOD
Document.make_indices()
PURPOSE
Make dictionary of indices Document.indices
The keys of Document.indices are Item types, and "master".
The values are sorted lists of Items of each type, and all Items.
USAGE
Call after read method
METHOD
Document.make_tree()
PURPOSE
Construct tree of parent and child items by constructing
Item.children list for each Item in namespace
USAGE
Call after read method
METHOD
Document.html_index(key,columns)
PURPOSE
Returns a string containing the html table containing an index
ARGUMENTS
key - key to index of interest in dictionary self.indices
columns - number of columns in html table
METHOD
Document.index_links()
PURPOSE
Returns a string containing hyper-links to indices and toc
METHOD
Document.write()
PURPOSE
Output documentation for a multi-file Document
USAGE
Call after read, make_indices, and make_tree methods
CLASS
InputFile
INSTANCE ATTRIBUTES
file - file object
line - last line read from file, without newline
METHODS
__init__(filename)- open file filename, assign to self.file
readline() - read and return next line, store in self.line
next_line() - find, store, and return the next non-blank line
read_string_dict() - read a dictionary, one key value pair per line
read_string_list() - read a string list, one string per line
METHOD
InputFile.readline()
PURPOSE
Reads and returns one line of file, saves in self.line
METHOD
InputFile.next_line()
PURPOSE
Returns next non-blank line
METHOD
InputFile.read_string_dict()
PURPOSE
Reads a dictionary of key and value string pairs, from a
file containing one key / value pair per line, with strings
delimited by blank space, until a blank line is encountered.
Returns a dictionary of key and value strings.
METHOD
InputFile.read_string_dict()
PURPOSE
Reads and a list of strings, with one string per line,
until a blank line is returned. Returns a list of strings
with leading and trailing white space removed.
METHOD
InputFile.read_path([root])
PURPOSE
Read absolute or relative path from next line of file, and
and return a corresponding absolute path. If input path name
is absolute, return the input. Otherwise, treat input path as
a relative path, relative to argument root (if present) or to
the current working directory (if root is not present).
FUNCTION
read_config(rc_filename)
PURPOSE
Reads data from file rc_filename.
Return a Document object with specified values for attributes:
src_dir, doc_dir, filenames, format, and access
Also sets values for Item and Section class attributes:
Item.types, Section.types, Section.ignore
FORMAT
The configuration file consists of a series of control lines,
most of which are followed by one or more lines containing data.
There may be no blank lines between the control line and the
associated data line(s), or between data lines. One or more blank
lines separate each control line and associated data line(s) from
the next control line. The recognized control lines and associated
data are:
'Item_types:' - dictionary of recognized Item types and
associated one character codes, e.g.,
'Section_types:' - list of recognized section headings
'Com_char:' - character used at beginning of item marker lines
'Src_dir:' - source directory path
'Doc_dir:' - documentation directory path
'Filenames:' - list of names of source files in Src_dir
'Format:' - format of output. Either 'html' or 'xml'
'Access:' - if 'private', include internal Items
- if 'public', exclude internal Items
'Done' - stop reading file, return from function
Lists (e.g., Section_types, and filenames) or dictionaries
(e.g., Item_types) are listed with one item, or one key/value pair,
per line. Directory paths may be either absolute or relative to
current working directory. The configuration file is read as an
infinite loop, which exits when the "Done" control line is read.
For examples of the required format, see the GDoc_rc.html or
GDoc_rc.latex file in the GDoc directory, which are used to
generate the html and latex versions of the documentation for
the GDoc module itself.
FUNCTION
link_namespace(line,namespace)
ARGUMENTS
line - a string
namespace - dictionary of Items accessed by name
RETURN
string line with Item names replaced by href links
FUNCTION
escape(a_string,format)
ARGUMENTS
a_string - string
format - output format. May be 'html', 'xml', or 'latex'
RETURN
Returns a copy of a_string appropriate for output in format,
in which special characters are replaced by escape sequences.
FUNCTION
header(title,format)
ARGUMENTS
title - title string for html or latex. Note used in xml.
format - output format. May be 'html', 'tex', or 'xml'
RETURN
A string containing a standard header for output file.
FUNCTION
footer(format)
ARGUMENTS
format - output format.
PURPOSE
Returns a string containing a standard footer for output
files in the specified format. Outputs null string for 'xml'
FUNCTION
find_directory(name)
PURPOSE
Searches python path and subdirectories of those in this path
for a directory with basename == name, and returns the absolute
path for this directory. Raises an error if the search fails.
SCRIPT
Main script
SOURCE
# Find GDoc source directory
GDoc_dir = find_directory('GDoc')
# Find configuration file
rc_filename = raw_input("Enter name of rc configuration file: ")
Doc = read_config(rc_filename)
Doc.read()
Doc.make_indices()
Doc.make_tree()
Doc.write()