Generating Forrest Sites
Part of making your modules ops ready is providing user documentation. CTL was developed to help that handoff and provides a "runbook" document that becomes your reference manual for your module's users.
Generating a web site
The ProjectBuilder module used to develop and build your module also contains support to generate a web site based on those module defintions. The generated web pages reads the type.xml file and generates a document suitable as a reference manual for your module, its attributes, commands, their options and anything else that makes up the definition of your module.
As the figure above illustrates, the tags in the type.xml files for your modules defined in in the modules source directory, are processed and along with some standard templates, an Apache Forrest document is generated.
Information is organized into a standard structure, divided up into sections, navigable via a top level table of contents.
- Displays information about your module library in HTML or PDF. Runbook can be deployed to any webserver.
- Gives an overview of your module's content.
- Describes all the attributes in your module along with their defaults.
- Describes all the commands in your module. This includes usage summary, command option description.
- You can embed your own information and graphics via Apache Forrest doc tags.
- Install Apache Forrest
The Runbook generation depends on Apache Forrest 0.8.
Follow these steps:
- Download and install Forrest v.0.8
- Confirm the
FORREST_HOMEenvironment variable is defined. (e.g.,
Generate the docs
The ProjectBuilder module includes the
generate-forrest-docs command to generate the Forrest site.
Outside an object context run the
generate-forrest-docs command accepting the defaults:
ctl -m ProjectBuilder -c generate-forrest-docs Base directory where module source files reside [/tmp/ctier/ctl/src] Target directory where build files are generated [/tmp/ctier/ctl/target] Library name? [default] --snip--
Or in an object context:
ctl -t ProjectBuilder -r training -c generate-forrest-docs --snip--
The first time you run the command, a Forrest site will be created in a new directory called "docs" under your base directory (and parallel to your modules directory).
You can run the
generate-forrest-docs command any time. Subsequent calls to the command will essentially re-run "forrest site".
Besides building a Forrest site, the
generate-forrest-docs command also copies a PDF formatted copy of each type's reference into its doc directory: type/doc/type.pdf. This reference is accessible after your module has been deployed and may be useful to end-users of your module.
generated-forrest-docs command does not rely on anything besides the content of your type.xml tags to generate the Forrest site, additional information can be quite useful to end users.
You can insert your own information into the documentation by using Forrest
<doc> ... </doc> tags. The
generated-forrest-docs command and templates attempt to keep the text inside your
doc tags close to the related element of your type.xml document.
Because you are free to use any Forrest
doc tags you can create some proffesional looking reference pages (including, tables, images, notes, warnings, etc.). See the Forrest 0.8 Documentation and note the DTD example docs, particularly document-v20.dtdx.html.
This page document-v20.html is a sample Forrest document with all the
View the site
After running the
generate-forrest-docs command you can view the produced output.
- Open the generated
forrest runto view the site via a running Jetty instance. (eg, browsing http://localhost:8888)
- Deploy the generated site.zip to a web server and extract the archive into a visible docroot directory.
Personalizing the Forrest site
Besides using Forrest
<doc>...</doc> tags, you can personalize the Forrest site through a number of settings.
The following ProjectBuilderSettings export attributes referened in the Forrest site template files used by
You can create instances of these Settings and associate those objects as resources to your ProjectBuilder object.