Date: 2004-03-29T09:48:27 Editor: AdamJack <[EMAIL PROTECTED]> Wiki: Gump Wiki Page: GumpRunDocumentation URL: http://wiki.apache.org/gump/GumpRunDocumentation
no comment Change Log: ------------------------------------------------------------------------------ @@ -1,13 +1,68 @@ == GumpRunDocumentation == -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]. == How things work today == -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. === 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 == --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]