CDI Specification document generation
This module contains AsciiDoc sources and configuration to generate CDI documentation in HTML and PDF format for both Apache License 2 and Java Community Process License.
Generating the documentation
mvn at the command line.
Maven will generate final doc in HTML and PDF in
target directory with the default license (ASL2).
License in doc
The documentation can be generated for 2 licenses : Apache License v 2.0 (by default) and JCP license.
To generate doc with various JCP licenses just change the
license-file property with one of the following value:
jcp-prefinal: for pre-final license
jcp-final-eval: for final evaluation license
jcp-final: for final implementation license
asl2: (default value) for Apache V2 License
mvn -Dlicense-file=jcp-prefinal will generate docs with JCP pref-final license.
Working on the spec
The spec is split different AsciiDoc file in
The master doc (entry point) is
cdi-spec.asciidoc which includes all the other part of the spec.
To work in the spec you may want to install a plugin in your IDE (major 3 IDE have AsciiDoc plugins). You can also use a good text editor providing AsciiDoc plugin. Best candidate are:
Install Atom. Then from the Atom editor menus, navigate to Atom › Preferences. From there, open the Packages tab and install:
- AsciiDoc Preview package
enables live preview
- AsciiDoc package
enables syntax highlighting (AsciiDoc language support)
Then from the Brackets file menu, open the extension manager.
Browse available extensions and install
To run AsciiDocFX, you will need to:
Using a web browser (preview only)
Editing the spec with Live Preview
If you want to more than just preview AsciiDoc files in your browser you may need to use an auto-generating mechanism and live preview in your browser. The spec provides script to help you setting up this configuration. Ìt only requires to have Ruby 1.8.7 or higher installed on your machine. More info on Ruby installation on https://www.ruby-lang.org/en/documentation/installation/
When Ruby is installed you’ll have to install bundler ruby gem with
gem install bundler command.
Then you can use it to install needed gems by entering the following command from
After that, just launch
preview.bat script to have the html version of the spec generated at each AsciiDoc change.
To have the generated html file automatically reload in your browser you may use
To use Chrome, Firefox or Opera to automatically preview change on your working doc, check out LiveReload. It describes itself as:
You can setup LiveReload (for free) on any operating system using the Guard::LiveReload plugin and the companion LiveReload extension for Chrome or Firefox. You can also install Chrome plugin in Opera with the chrome support extension
|After installing the Chrome LiveReload extension, you need to check the "Allow access to file URLs" checkbox in Tools > Extensions > LiveReload in order for it to work with local files.|
Whenever the AsciiDoc file is changed, first the Guard "shell" plugin will be triggered to generate the HTML file, then the "livereload" plugin will be triggered to send the HTML to the browser.