Generating and Publishing Avalon Documentation

This HOWTO discusses how to generate and publish our documentation from the XML source files in CVS.

Generating Documentation

Site documentation is can be broken up into two categories:

• General site information (the main links on http://avalon.apache.org) 2. Project-specific documentation (things like http://avalon.apache.org/merlin)
• Project specific docs are located with the project's source code, generally in a directory named "xdocs" but this may very slightly from project to project – something we certainly want to standardize at some point.
  

The general documentation is in the avalon-site module. The newer documentation is under the 'xdocs' directory (not the 'src' directory which containers outdated information). To build this documentation use maven and run:

maven site:generate

The documentation will be generated and placed it 'target/docs'.

Publishing Documentation to the Site

The contents under avalon-site/site are what end up being published to the website via a cron job (that does a CVS update). Therefore, to publish new documentation to the site, one needs to :

• Check out the avalon-site module
• Update the XML source under xdocs
• Run maven site to generate the HTML documents
• Import or move the new HTML from avalon-site/target/site to avalon-site/site
• Commit your changes to both the XML source and the HTML results (under avalon-site/site)
  

For project specific documentation, update the project's XML documentation and import the generated HTML into the appropriate location in the avalon-site/site CVS module.