[table of contents] [master index] [functions] [scripts] [methods] [modules] [classes]

### TABLE OF CONTENTS

- module GDoc

- class Section

- method Section.write

- class Item

- method Item.read
- method Item.write
- method Item.html_ref
- method Item.html_link
- method Item.set_depth
- method Item.html_toc

- class SrcFile

- method SrcFile.read
- method SrcFile.write

- class Document

- method Document.read
- method Document.make_indices
- method Document.make_tree
- method Document.html_index
- method Document.index_links
- method Document.write

- class InputFile

- method InputFile.readline
- method InputFile.next_line
- method InputFile.read_string_dict
- method InputFile.read_string_list
- method InputFile.read_path

- function read_config
- function link_namespace
- function escape
- function header
- function footer
- function find_directory
- script Main

## GDoc

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.

## Section

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'

## Section.write

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

## Item

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

## Item.read

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

## Item.write

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

## Item.html_ref

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

## Item.html_link

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

## Item.set_depth

METHOD

          Item.set_depth(depth)

PURPOSE

          Sets depth attribute of self and all of its descendants.

## Item.html_toc

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.

## SrcFile

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

## SrcFile.read

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

## SrcFile.write

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

## Document

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

## Document.read

METHOD

          Document.read()

PURPOSE

          Extract documentation for a multi-file Document

## Document.make_indices

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

## Document.make_tree

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

## Document.html_index

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

## Document.index_links

METHOD

          Document.index_links()

PURPOSE

          Returns a string containing hyper-links to indices and toc

## Document.write

METHOD

          Document.write()

PURPOSE

          Output documentation for a multi-file Document

USAGE

          Call after read, make_indices, and make_tree methods

## InputFile

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

## InputFile.readline

METHOD

         InputFile.readline()

PURPOSE

         Reads and returns one line of file, saves in self.line

## InputFile.next_line

METHOD

         InputFile.next_line()

PURPOSE

         Returns next non-blank line

## InputFile.read_string_dict

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.

## InputFile.read_string_list

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.

## InputFile.read_path

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).

## read_config

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.

## link_namespace

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

## escape

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.

## header

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.

## footer

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'

## find_directory

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.

## Main

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()