140 lines
4.2 KiB
Plaintext
140 lines
4.2 KiB
Plaintext
|
|
||
|
|
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
|