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
