3:41 a.m.
User development,
The document "Building JBoss Tools Documentaion", was updated Jan 20, 2010
by Max Andersen.
To view the document, visit:
http://community.jboss.org/docs/DOC-13341#cf
Document:
--------------------------------------------------------------
You can download a folder with a plug-in either from a
http://anonsvn.jboss.org/repos/jbosstools or a https://svn.jboss.org/repos/jbosstools ( if
you have commiter rights) repsositories . In the plug-in's folder you will find a
directory with documentation.This instruction explains how you can build the
documentation.
h3. Prerequisites
1.Maven building tool
2.You need to make sure you have downloaded all required files and folder from the
repository:
a) Plug-in folder
b) the +*documentation*+ folder
3.Maven requires a number of plug-ins (jDocBook etc.) to generate JBoss Tools
documentation and therefore you need to specify where Maven can download those
plug-ins. The easiest way is to create a new profile in the Maven configuration file
(*+settings.xml+*). You will find the file in *%M2_HOME%/conf/* or *%USER_HOME%/.m2/*.
Open the *+settings.xml+* and add the following profile:
<profile>
<id>documentation</id>
<repositories>
<repository>
<id>maven2-repository.dev.java.net</id>
<name>Java.net Repository for Maven</name>
<url>http://download.java.net/maven/1</url>
<layout>legacy</layout>
</repository>
<repository>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
</snapshots>
<id>repository.jboss.com</id>
<name>Jboss Repository for Maven</name>
<url>http://repository.jboss.com/maven2/</url>
<layout>default</layout>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
</snapshots>
<id>repository.jboss.com</id>
<name>Jboss Repository for Maven</name>
<url> http://repository.jboss.com/maven2/ </url>
<layout>default</layout>
</pluginRepository>
<pluginRepository>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
<id>snapshots.jboss.org</id>
<name>Jboss Snapshots Repository for Maven</name>
<url>http://snapshots.jboss.org/maven2/</url>
<layout>default</layout>
</pluginRepository>
</pluginRepositories>
</profile>
Then you need to activate the profile if you want to use it permanently. Find the
+<activeProfiles>+ tag and add this line as a child element:
<activeProfile>documentation</activeProfile>
Otherwise you should explicitly activate the profile with *-P profile_name* option while
building the documentaion.
h3. Building Steps
So, you checked out the plug-in for which you want to build documentation and the
documentation folder. And now you can proceed to building the documentation.
1.Find the +*pom.xml*+ file, that is responsible for building the documentation, in the
plug-in folder you downloaded. Normally it’s located in “/docs/reference”.
2.Run *mvn clean install* or *mvn clean install -P profile_name* (if you didn't
activate your profile in Maven's *+settings.xml+*) command in the folder with
*+pom.xml+* to start building the documentation.
Example:
user@user-desktop:/home/user/trunk/seam/docs/reference$ mvn clean install
3.If everything is configured correctly you will see a “BUILD SUCCESSFUL” message. You
will also see a generated *+target+* folder that contains the built documentation.
Example:
To open the HTML version of the “Seam Dev Tools Reference Guide” guide you need to proceed
to
user@user-desktop:/home/user/trunk/seam/docs/seam/docs/reference/target/docbook/publish/en-US/html_single
and open index.html file.
h3. Documentation Profiles
There are 3 profiles that you can build documentation with:
*release* builds release documentation with “new” or “updated” markers next to the
corresponding chapters and sections titles
*releaseJBDS* builds release documentation with Jboss.com styles for commercial products
*diffmk* builds documentation with markers highlighting changes comparing to the previous
release version and sets “new” or “updated” markers next to the corresponding chapters and
sections titles.*Note:* Please make sure that you have the master_output.xml file
(normally the file can be found in \pluginName\docs\reference\en\) as a new guide may not
have such file since there's nothing to compare with.
This command launches building documentation with a profile.
mvn install -Pprofile_name
By default, with no profile specified, Night Build docs are generated.
In order to build all the guide from one place you need to have JBoss Tools trunk checked
out then cd to JBoss_tools_trunk/documentation/jbds-docs/ to build JBDS guides with
jboss.com styles or to JBoss_tools_trunk/documentation/jboss-tools-docs to build JBoss
Tools guides.
and run
mvn clean install assembly:assembly
You can optionally use a profile in this command.
mvn clean install assembly:assembly -Pprofile_name
--------------------------------------------------------------