Online javadocs for Tuscany Web site

[Simon Nash <na...@hursley.ibm.com>]

I've been looking into how we could put online javadocs for M2 SCA and SDO
on the Tuscany web site.  Ideally these would be generated from the tagged
M2 source files rather than being maintained separately in svn.

I'm new into this, so my solution may not be the best.  However, it does
work (for me at least) and AFAIK the javadocs that it creates are identical
to those that we are releasing in the M2 downloads for SCA Java and SDO Java.

At the moment I'm using a Windows bat file "build-docs.bat" (attached to
this email) to check out the necessary API/SPI source files at the tagged
M2 level and then run "mvn javadoc:javadoc" on them.  I'll be happy to turn
this into an ant task or maven project when we are all OK with the process.

To generate M2 javadocs using this bat file, you need to do the following:

1. Create an empty top-level directory.

2. Either copy build-docs.bat to this directory, or make sure it is
    accessible from your PATH.

3. cd to this top-level directory, and run "build-docs.bat".

4. After the command has completed, the javadoc output will be in
    a subdirectory "apidocs" under the top-level directory.  It is
    organized into the following subdirectories:
      apidocs/sca          SCA spec APIs
	 apidocs/commonj      commonj spec APIs
	 apidocs/sdo          SDO spec APIs
	 apidocs/tuscany-sca  Tuscany SCA APIs, host APIs, and SPIs
	 apidocs/tuscany-sdo  Tuscany SDO APIs and implementation classes

    There's another subdirectory "apisource" that contains the sources
    from which the javadocs were generated.  The contents of this directory
    aren't needed for publication.

5. The content under "apidocs" is the set of M2 javadocs that should be
    published as online javadocs on the Tuscany web site.

As I understand it, in order to publish these files to the official
incubator.apache.org/tuscany site, they would need to first be checked
into svn under tuscany/site/site-publish.  It seems very undesirable
to perform a mass check-in of generated files in this way.  Can anyone
suggest an alternative approach for publishing them that avoids the
need to do this check-in?

   Simon