contributing.asciidoc

Contributing to the RichFaces Documentation

Table of Contents

• Building the RichFaces doc
• Editing the documentation using guard and livereload

The RichFaces project uses a docbook toolchain to generate it’s documentation. Starting with RichFaces 4, we are generating our docbook xml from asciidoc source.

Building the RichFaces doc

To build the RichFaces documentation, execute the following command:

1. Generate the PDF, html_single, and html files

   With the docbook generated we can execute our docbook toolchain to generate the PDF, html_single, and html files using the maven build.

   mvn clean install

Editing the documentation using guard and livereload

The asciidoc source can be edited using any text editor. However, if you’d like re receive rapid feedback on how the docs are evolving, you can enable guard and livereload to see your changes live in your browser.

To use guard and livereload with the RichFaces docs, follow the following steps

Note

These aren’t meant to be exhaustive steps for installing and configuring guard and livereload, rather it’s a recipe of how to use these tools as they are configured for working with the RichFaces docs. For more detailed instructions, see this excellent resource: http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

1. Initialize your ruby environment

   Note	Make sure you have ruby >= 1.9.2 installed, and the bundle gem. You will also need the livereload plugin installed in your browser.

   The docs come with a bundled Gemfile that is used to initialize your ruby environment as follows:

   bundle install

2. Start guard

   The docs come pre-configured with a Guardfile used to configure guard to listen for asciidoc changes, and generate html directly using asciidoctor. To run guard do:

   bundle exec guard start

3. Connect your browser

   Connect your browser to livereload by navigating to either of the files:

   1. Component_Reference/target/docbook/en-US/Component_Reference.html

   2. Developer_Guide/target/docbook/en-US/Developer_Guide.html

   Then activate the livereload plugin in your browser. As you save changes to the asciidoc source, you will see those changes reflected in the browser within seconds.