Differences between revisions 1 and 2
Revision 1 as of 2004-03-29 17:07:31
Size: 374
Editor: 1Cust191
Comment:
Revision 2 as of 2004-03-29 17:48:27
Size: 3166
Editor: 1Cust191
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
Gump Run Documentation is documentation about a Gump run, not about [http://gump.apache.org|Gump]. Gump Run Documentation is documentation about a Gump run, not about [http://gump.apache.org Gump].
Line 7: Line 7:
Gump currently supports two forms of documentation (plain text and xdocs, for[http://xml.apache.org/forrest|Apache Forrest]). Gump currently supports two forms of documentation (plain text and xdocs, for[http://xml.apache.org/forrest Apache Forrest]). The reason for this is that although Forrest generates impresive sites, it is time consuming and not ubiquitously available. Folks have the choice of simple/cheap or pretty.

=== Overview ===

Currently 'documentation' is a task performed at the end of a run, so it has the all context (states, outcomes) available. This is important for 'statistics' and 'xref' pages, which display pages that compare/sort all modules/projects so needs all to be complete, and have complete information.

Note: That said, this could be split into two parts -- with pages for single modules/projects being creates as available (much sooner) and only the cross entity pages created last.

=== Implementation ===

Documented is achieved using a few classes:

* Resolver -- that resolves a model object (e.g. a project) to a URL or file.
* Documenter -- that works with it's resolver to generate those files.
Line 11: Line 24:
This component is important in part because other aspects (e.g. RSS|Atom feeds, Notification e-mails) need to be able to refer to some aspect (a failed work item, a project page) without knowing which documenter was user. Also, this can be quite complicated (especialyl for Forrest with content and content/xdocs) and we need to centralize the logic to avoid duplication/error.
Line 13: Line 28:
This component is the meat of the documentation process. A GumpRun (with complete information) is traversed, and information is generated for all entities in the GumpSet (a list or dependency stack).

Two documentation classes exist as sub-classes of gump.documentation.Documenter:

* gump.documentation.ForrestDocumenter
* gump.documentation.TextDocumenter

=== ForrestDocumenter ===

This module is huge, but that is only because it has a lot of repetative (template-ish) code.

The overall algorythm used for documentation is:

 Document the workspace (see block below)
 For each module in workspace:
  If module not in gump set: continue
  Document the module (see block below)
  For each project in module:
   If project not in gump set: continue
   Document the project(see block below)

Basically each block looks like this:

 * Select a file for an entity (the resolver determines the name/where)
 * Generate xdoc sections (e.g. details, or dependencies or)
 * Generate details by adding paragraphs or lists/list items as needed.
 * Iterate through information (e.g, annotations) adding tables/rows/data.
 * Serialize the xdocs (DOM-like tree) to that file.
 * Throw away all memory used by the tree.

Note: Some re-used blocks are:

 * Generate a section (with table with rows/data) for all Annotations
 * Generate a section (with table with rows/data) for all Files held by FileHolder
 * Generate a section (with list/items) for Statistics

=== xdocs ===


GumpRunDocumentation

Gump Run Documentation is documentation about a Gump run, not about [http://gump.apache.org Gump].

How things work today

Gump currently supports two forms of documentation (plain text and xdocs, for[http://xml.apache.org/forrest Apache Forrest]). The reason for this is that although Forrest generates impresive sites, it is time consuming and not ubiquitously available. Folks have the choice of simple/cheap or pretty.

Overview

Currently 'documentation' is a task performed at the end of a run, so it has the all context (states, outcomes) available. This is important for 'statistics' and 'xref' pages, which display pages that compare/sort all modules/projects so needs all to be complete, and have complete information.

Note: That said, this could be split into two parts -- with pages for single modules/projects being creates as available (much sooner) and only the cross entity pages created last.

Implementation

Documented is achieved using a few classes:

* Resolver -- that resolves a model object (e.g. a project) to a URL or file. * Documenter -- that works with it's resolver to generate those files.

Resolver

This component is important in part because other aspects (e.g. RSS|Atom feeds, Notification e-mails) need to be able to refer to some aspect (a failed work item, a project page) without knowing which documenter was user. Also, this can be quite complicated (especialyl for Forrest with content and content/xdocs) and we need to centralize the logic to avoid duplication/error.

Documenter

This component is the meat of the documentation process. A GumpRun (with complete information) is traversed, and information is generated for all entities in the GumpSet (a list or dependency stack).

Two documentation classes exist as sub-classes of gump.documentation.Documenter:

* gump.documentation.ForrestDocumenter * gump.documentation.TextDocumenter

ForrestDocumenter

This module is huge, but that is only because it has a lot of repetative (template-ish) code.

The overall algorythm used for documentation is:

  • Document the workspace (see block below) For each module in workspace:
    • If module not in gump set: continue Document the module (see block below) For each project in module:
      • If project not in gump set: continue Document the project(see block below)

Basically each block looks like this:

  • Select a file for an entity (the resolver determines the name/where)
  • Generate xdoc sections (e.g. details, or dependencies or)
  • Generate details by adding paragraphs or lists/list items as needed.
  • Iterate through information (e.g, annotations) adding tables/rows/data.
  • Serialize the xdocs (DOM-like tree) to that file.
  • Throw away all memory used by the tree.

Note: Some re-used blocks are:

  • Generate a section (with table with rows/data) for all Annotations
  • Generate a section (with table with rows/data) for all Files held by FileHolder

  • Generate a section (with list/items) for Statistics

xdocs

How we could take them forward

GumpRunDocumentation (last edited 2009-09-20 23:49:32 by localhost)