You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Bhuvaneswaran A <bh...@collab.net> on 2009/12/04 10:57:34 UTC
[Proposal] Publishing api doc for Subversion
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@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
Re: [Proposal] Publishing api doc for Subversion
Posted by Bhuvaneswaran A <bh...@collab.net>.
Thanks, Julian.
Committed the Hudson jobs in r887496.
On Fri, 2009-12-04 at 11:02 +0000, Julian Foad wrote:
> Bhuvaneswaran A wrote:
> > 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@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
>
> +1 to all of that. Thanks for doing this!
>
> - Julian
>
>
>
--
Bhuvaneswaran A
CollabNet Software P Ltd. | www.collab.net
Re: [Proposal] Publishing api doc for Subversion
Posted by Julian Foad <ju...@btopenworld.com>.
Bhuvaneswaran A wrote:
> 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@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
+1 to all of that. Thanks for doing this!
- Julian