From ControlTier

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.

Contents 1 Generating a web site 2 Generate the docs 3 Use "doc" tags! 4 View the site 5 Personalizing the Forrest site

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:

1. Download and install Forrest v.0.8
2. Confirm the FORREST_HOME environment variable is defined. (e.g., echo $FORREST_HOME).

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.

Use "doc" tags!

While the 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 doc tags.

View the site

After running the generate-forrest-docs command you can view the produced output.

• Open the generated doc/build/site/index.html
• Use forrest run to 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 generate-forrest-docs:

• ProjectBuilderForrestHome
• ProjectBuilderProjectName
• ProjectBuilderProjectDescription
• ProjectBuilderOrganizationName
• ProjectBuilderOrganizationDescription
• ProjectBuilderOrganizationURL
• ProjectBuilderProjectURL

You can create instances of these Settings and associate those objects as resources to your ProjectBuilder object.