JdbcMapper/docs/how_to_contribute_docs.txt

Contributing Documentation to Beehive
=====================================

Introduction
------------

Beehive documentation is created using Apache Forrest--a tool for
building web sites from XML source docs.  

To contribute documentation you must first install Forrest on 
your local machine.  For installation details see:

  beehive/trunk/BUILDING.txt

Forrest documentation is in the form of XML files, so it is a good idea
to use a tool that is able to validate XML during authoring.  The XML
source files must be valid for the Beehive documentation to build
successfully.

Note, the paths below are referenced relative to the SVN root:

  beehive/trunk

In addition, instructions for updating the Beehive website are included
below. 

Authoring Documentation
------------------------

Beehive stores its Forrest XML files in one of two directories:

  docs/forrest/release/src/documentation/content/xdocs

contains the documentation for a specific Beehive release and is
made available at the URL:

  http://beehive.apache.org/release/<release-number>

The directory: 

  docs/forrest/site/src/documentation/content/xdocs

contains the documentation for the Beehive website and maps to the 
URL:

  http://beehive.apache.org/

The command-line examples below assumes that you are authoring documentation 
for a Beehive release.

The XML source files are transformed by the Forrest tool into 
an HTML web site.  Forrest XML contains many idiomatic shorthand 
expressions for referencing common HTML elements, esp. HTML links.
For details on this shorthand see 

  http://forrest.apache.org/docs/linking.html

The basic development cycle for Beehive documentation runs as follows:

(1) Turn on the Jetty Server

The Jetty server is a web server / Servlet container provided by Forrest 
used to view/test the Forrest docs while they are development.

To turn on the Jetty Server, run the following Ant command:

  docs/forrest/release> ant run

Once the Jetty Server has been turned on, it is automatically aware of the
Forrest XML files in:

  /docs/forrest/src/documentation/content/xdocs

Any changes you make to these XML files, will automatically be reflected 
in the HTML served up the Jetty server.

(2) Edit the Forrest XML source

Make the desired changes to the Forrest XML source files.  Your changes should 
result in valid XML documents according to the appropriate Forrest DTDs, specifically
that available at:

  http://forrest.apache.org/dtd/document-v20.dtd

While editing Forrest XML files, it is helpful to use an authoring environment
that can validate XML files.  Invalid XML files will break the Beehive build.

(3) View the changes to the documentation

During authoring, changes can be viewed dynamically via a web browser by visiting:

  http://localhost:8888/index.html

Repeat steps (2) and (3) to make iterative edits to the Forrest XML files.

(4) Committing changes to documentation

Changes to the Forrest XML files should be committed after ensuring that the 
release / site documentation builds succeed successfully.  To ensure that the
release build succeeds, run:

  docs/forrest> ant build.release

To ensure that the website build succeeds, run:

  docs/forrest> ant build.site

Additional instructions for editing the website are included below.

Updating the Website
--------------------

The website is decoupled from the Beehive release documentation, though at the time
of this writing, they are both checked into trunk/.

To update the website, make any modifications in docs/forrest/site/.  Then, build the 
documentation with:

  cd docs/forrest
  ant build.site

The build should complete without any errors.  Once this is complete, the website
can be staged using:

  ant stage.site

This will copy the website atop the docs/forrest/www directory.  Run 'svn status' and
ensure that the Forrest files you changed are reflected in the HTML / PDF files that 
Forrest generated.  

Once this is done, run 'svn commit' to submit the changes to docs/forrest/www to 
source control.  The website can be updated by checking it out of Subversion onto the 
Apache web server.  To do this, run:

  svn commit
  ssh minotaur.apache.org
  cd /www/beehive.apache.org
  svn update http://svn.apache.org/repos/asf/beehive/docs/forrest/www