Contributing to the RichFaces Documentation
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:
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
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/
Initialize your ruby environmentNote
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:
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
Connect your browser
Connect your browser to livereload by navigating to either of the files:
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.