Apache XML Forrest

the Apache XML site
 
   

Forrestbot introduction

PDF
PDF

Getting started with using Forrestbot

Goal

You have your own project and you want to use Forrest to build the project documentation.

Introduction

The ForrestBot will automatically build and publish your documentation on a regular basis. The versatile ForrestBot can retrieve source XML instances from various type of repository (e.g. local filesystem, local CVS, remote CVS), generate the documents, and copy the result to a local or remote location (optionally via secure methods). It can be run from the command-line as part of your documentation edit-build-review cycle, it can be called from cron to automate your website update, it can operate as a centralised docs-build service for a set of remote projects, it can do tasks in parallel, and do even more. See some websites that are automatically built with ForrestBot at http://forrestbot.cocoondev.org/

This document provides a concise overview of one particular scenario. See The ForrestBot for details and understand Our Contract. We assume that you have built and configured Forrest as described in Using Forrest.

Please send your feedback to forrest-dev - the ForrestBot will be enhanced to meet diverse needs.

(Building the documentation for the actual Forrest project is a separate issue. Use ./build.sh site ... that will provide overview documentation about how Forrest operates and how you can help to improve it.)

Establish project source directory

The directory that contains your XML instances.

  • PROJECT_HOME = /home/you/yourproject
  • SRC_DOC = $PROJECT_HOME/src/documentation

Your XML instance documents are at $SRC_DOC/content/xdocs

Establish project configuration

See the sample configurations at xml-forrest/src/resources/forrestbot/samples/ copy one and edit it to replace the <project> definitions with our own, i.e.

  <project name="yourProject-local">
    <prepare>
        <skin name="forrest-site"/>
    </prepare>
    <get-src type="local-copy">
      <project-dir name="/home/you/yourproject" />
      <content-dir name="/home/you/yourproject/src/documentation"/>
    </get-src>
    <deploy type="local-copy">
      <destination name="/var/www/html/yourproject"/>
    </deploy>
  </project>

Run ForrestBot

[you@locahost]$ cd $PROJECT_HOME
[you@locahost]$ forrestbot -Dbot.config=<name>
... where <name> is the pathname to your configuration file.

There are also convenience scripts for automation. See xml-forrest/src/resources/forrestbot/scripts/README.txt

Next Steps

Some enhancements to your ForrestBot would be ...

  • Add your own skin as described in Using Forrest.
  • Configure another <project> to conduct a secure copy to your public website.
  • Instruct ForrestBot to send you email about the activities.
  • Manage your XML instances with CVS and instruct ForrestBot to get the source.
  • Use the "Forrestbot web interface" (website staging application). xml-forrest/src/resources/forrestbot/webapp/WEB-INF/README.txt

Other methods

See the Using Forrest document.

Forrest can also run as a dynamic webapp.

by David Crossley; 0.2