Doc plan for Beta

[Steve Hanson <st...@bea.com>]

Hi all:

To improve the doc build, I would really like to introduce a dependency on Apache Forrest.  (The "live site" (http://incubator.apache.org/beehive/) is currently generated using Forrest.)
On this plan, to call "ant docs" (or "ant build.dist") you would need to have Forrest installed on your machine.

Versioning of the docs is the main benefit.  There will be a single target to call to re-create the live site docs for any given branch/release.  (Many Apache projects don't do this, and so their docs become a mish-mash: you're always asking yourself, "Does this topic apply to my release?")
  A secondary benefit is a clean up of the doc build: there will a single doc target, with a single doc artifact (= the live site for whichever release), instead of a bunch of disconnected processes that I cobble together on my machine. 


The Details
-----------

-- Requirements

I plan to checkin Forrest 0.6 at 

 /trunk/externals/forrest/apache-forrest-0.6.zip

Bootstrapping would unzip into 

 /trunk/installed/forrest/...

The xml content (from which the HTML web site is gen'd) would live at

 /trunk/docs/forrest/src/...

Building the docs (calling )

-- The Build

Running "ant docs" and "ant build.dist", will (1) call into Forrest, which generates a copy of the live site (for a given branch/release) and (2) call Javadoc on all of the subprojects.  Finally (1) and (2) are slapped together to form the doc set for a given release.

The distribution structure will appear as follows:

trunk
  build
    dist
      apache-beehive-incubating-XXX
        docs
          javadoc
	    controls
          netui
          wsm
          [etc]
          index.html

Comments, concerns, and questions are appreciated.

-Steve Hanson