[Gump Wiki] Updated: GumpRunDocumentation
Date: 2004-11-17T04:54:35 Editor: JanMatèrne [EMAIL PROTECTED] Wiki: Gump Wiki Page: GumpRunDocumentation URL: http://wiki.apache.org/gump/GumpRunDocumentation spell check Change Log: -- @@ -25,7 +25,7 @@ Also, calculating the URL/path can be quite complicated (especially for Forrest with content and content/xdocs, and with safe naming) and we need to centralize the logic to avoid duplication/error. - Complicatng Factors + Complicating Factors Forrest content goes into content (eg. images), or content/xdocs (e.g. xdoc pages). The resolver needs to know this for when it generates files, but not for when it generates URLs (since they are merged here). - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
[Gump Wiki] Updated: GumpRunDocumentation
Date: 2004-11-17T04:56:59
Editor: JanMatèrne [EMAIL PROTECTED]
Wiki: Gump Wiki
Page: GumpRunDocumentation
URL: http://wiki.apache.org/gump/GumpRunDocumentation
spell check
Change Log:
--
@@ -38,7 +38,7 @@
* gump.documentation.ForrestDocumenter
* gump.documentation.TextDocumenter
- Complicatng Factors
+ Complicating Factors
Given that forrest is used to generate the site, additional content
(server.xml, *.rss|*.atom feed) and other non-documentation artifacts, has to
be placed into {forrest-work}/src/documentation/content after the template is
syncronized in, and before the forrest run occurs. As such the Documenter
'interface' has a prepare() method that allows the sub-class to implement
prepareRun() or not. This is called prior to those syndication/results steps,
and before documentation.
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
[Gump Wiki] Updated: GumpRunDocumentation
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]
[Gump Wiki] Updated: GumpRunDocumentation
Date: 2004-03-29T10:01:14 Editor: AdamJack [EMAIL PROTECTED] Wiki: Gump Wiki Page: GumpRunDocumentation URL: http://wiki.apache.org/gump/GumpRunDocumentation no comment Change Log: -- @@ -21,7 +21,9 @@ === 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. +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 entity (a failed work item, a project page) without knowing which documenter was used. + +Also, calculating the URL/path can be quite complicated (especially for Forrest with content and content/xdocs, and with safe naming) and we need to centralize the logic to avoid duplication/error. === Documenter === @@ -46,7 +48,7 @@ If project not in gump set: continue Document the project(see block below) -Basically each block looks like this: +Basically blocks looks like this: * Select a file for an entity (the resolver determines the name/where) * Generate xdoc sections (e.g. details, or dependencies or) @@ -61,8 +63,14 @@ * Generate a section (with table with rows/data) for all Files held by FileHolder * Generate a section (with list/items) for Statistics +There are some helper methods for displaying a state icon for an entity. + === xdocs === +This is a home grown, DOM-like, approach. A basic XDocPiece base class exists that is sub-classes for Document or Section or Paragraph, etc. These classes have createX methods that allow creation of sub-elements into it's own list of children. Effectively, this encapsulates the xdoc rules in code, since not child can be created without a method on the parent. + +Helper methods exist make common combinations, e.g. to create a Table and add titles from a list of strings, e.g. to add a line to a table with title/value, two datum. +When a XDocDocument is serialized it recursively outputs the tag (e.g. P), outputs it's children (including text nodes), then outputs it's closed tag (e.g. /P). == How we could take them forward == - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
[Gump Wiki] Updated: GumpRunDocumentation
Date: 2004-03-29T14:41:57
Editor: AdamJack [EMAIL PROTECTED]
Wiki: Gump Wiki
Page: GumpRunDocumentation
URL: http://wiki.apache.org/gump/GumpRunDocumentation
no comment
Change Log:
--
@@ -12,6 +12,21 @@
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.
+=== Complicatng Factors ===
+
+Given that forrest is used to generate the site, additional content (server.xml,
*.rss|*.atom feed) and other non-documentation artifacts, has to be placed into
{forrest-work}/src/documentation/content after the template is syncronized in, and
before the forrest run occurs. As such the Documenter 'interface' has a prepare()
method that allows the sub-class to implement prepareRun() or not. This is called
prior to those syndication/results steps, and before documentation.
+
+{{{
+#
+# Call a method called 'prepareRun(run)', if needed
+#
+def prepare(self,run):
+if not hasattr(self,'prepareRun'): return
+if not callable(self.prepareRun): return
+log.info('Prepare to document run using [' + `self` + ']')
+self.prepareRun(run)
+}}}
+
=== Implementation ===
Documented is achieved using a few classes:
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
