As per discussion we had in this email thread [1] about publishing api
doc, I checked other projects and also had a discussion at
general_at_incubator list. The details about the conversation we had with
incubator team can be found here [2]. Here's my proposal based on the
findings.
Other Apache projects follow different approach. Few projects publish
api doc in site/ directory in Subversion repository. The apr, jakarta,
hadoop projects are a few to name. I don't think this approach is
feasible for Subversion. We wouldn't want to commit the api docs in the
repository periodically to publish them online.
Few projects like lucene/tika generate api documentation using Hudson
and publish them in people.apache.org by running a cron job that can
rsync the build results from Hudson -> people.apache.org. This involve
custom setting at people.apache.org tied to a particular developer.
Considering these aspects, here's my proposal:
The Hudson has a inbuilt feature to publish html content if placed in
userContent folder. The javadoc publishing capability is already present
in Hudson. Taking advantage of both these Hudson features, I'm thinking
a) configure the job(s) to generate doxygen and javadoc documentation.
b) create a link to this document to userContent. With this setup, the
documentation can be made available here:
doxygen:
http://hudson.zones.apache.org/hudson/userContent/subversion/doxygen/index.html
javadoc:
http://hudson.zones.apache.org/hudson/userContent/subversion/javadoc/index.html
We may configure this job to run on daily basis.
AFAIK, in the past we did not publish doxygen/javadoc for stable
releases in Subversion project. If we had to so, we may place them in
our repository under site/ directory corresponding to that release. The
documentation for trunk aka. on-going changes can be made available in
the above url which we may link it from our home page, if need be.
To publish document in this fashion, all we should do is create
Hudson job(s) appropriately. Comments?
[1] http://tr.im/GBGH
[2] http://tr.im/GBIg
--
Bhuvaneswaran A
CollabNet Software P Ltd. | www.collab.net
Received on 2009-12-04 11:58:15 CET