XDoclet 2 - Maven2 plugin

Maven2 plugin

(!)This is a temporary page dedicated to the maven2 plugin for xdoclet2. The information it contains might be innacurate and certainly subject to change.

Foreword

To use this plugin, you will need maven 2.0.1 or a more recent version. It will not work with 2.0.0, due to a bug in the plugin dependencies classloading. (See MNG-1804@jira)

This is based on Espen Amble Kolstad's contribution from XDOCLET-38@jira, so kudos to him.

It seems to me this plugin could be the nicest way to use xdoclet2, because you will not need to have 3 gazillion dependencies in your projects anymore. The only dependencies you'll have to specify will the the xdoclet-plugins you want to use - and they will not be in your project main dependencies, but in build/plugins/dependencies, so they're really isolated from your actual project.

Reading this document shouldn't prevent you from learning the basic maven usage. Read maven docs at http://maven.apache.org

Reading this document shouldn't prevent you from getting basic XDoclet2 knowledge.

Installation

If you only want to try and install the xdoclet2-maven2 plugin on your local machine, you can build and install it from source by running

mvn clean install

or download the plugin jar from here and run the following:

mvn install:install-file -DgroupId=xdoclet -DartifactId=maven2-xdoclet2-plugin
                               -Dversion=2.0.5-SNAPSHOT -Dpackaging=maven-plugin
                               -Dfile=<path-to-file>

where <path-to-file> is the path to the plugin jar you just downloaded.

... But it's probably better to:

Stay up-to-date

If you want to stay up-to-date while this plugin is being worked on, you should add this to your pom's project/pluginRepositories element:

<pluginRepository>
  <id>codehaus-plugins</id>
  <url>http://dist.codehaus.org/</url>
  <layout>legacy</layout>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
  <releases>
    <enabled>true</enabled>
  </releases>
</pluginRepository>

Usage

To use the plugin, add the following to your pom: (of course, skip the <build> tag if you already have a build section)

Of course this is a sample. Please get to know XDoclet2 and how it generally works before complaining that this doesn't work. (this is real snippet used to build

xdoclet2 plugins). For real life usage you need to consult documentaton on plugins you

like to use

<build>
            <plugins>
                <plugin>
                    <groupId>xdoclet</groupId>
                    <artifactId>maven2-xdoclet2-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>xdoclet</id>
                            <phase>generate-sources</phase>
                            <goals>
                                <goal>xdoclet</goal>
                            </goals>
                        </execution>
                    </executions>
                    <!--
                        since maven plusgin does not specify dependencies
                        on concrete xdoclet-2 plugins, you must specify them 
                        explicitely. as well as dependencies which may be needed by 
                        plugin itself
                    -->
                    <dependencies>
                        <dependency>
                            <groupId>xdoclet-plugins</groupId>
                            <artifactId>xdoclet-plugin-qtags</artifactId>
                            <version>1.0.4-SNAPSHOT</version>
                        </dependency>
                        <dependency>
                            <groupId>xdoclet-plugins</groupId>
                            <artifactId>xdoclet-taglib-qtags</artifactId>
                            <version>1.0.4-SNAPSHOT</version>
                        </dependency>
                    </dependencies>
                    <goals>
                        <goal>xdoclet</goal>
                    </goals>
                    <configuration>
                        <configs>
                            <!--
                              each config defines single xdoclet2 run
                              for some plugins. more than one run can be specified with
                              different parameters
                            -->
                            <config>
                                <components>
                                    <!--
                                       components are xdoclet2 plugins to be run
                                       and sometimes configuration objects
                                    -->
                                    <component>
                                        <!-- classname of the component -->
                                        <classname>org.xdoclet.plugin.qtags.impl.QTagImplPlugin</classname>
                                    </component>
                                    <component>
                                        <classname>org.xdoclet.plugin.qtags.impl.QTagLibraryPlugin</classname>
                                        <!--
                                            components can be configured with parameters
                                            configuration specified here overrides common configuration settings
                                            for config
                                         -->
                                        <params>
                                            <packagereplace>org.xdoclet.plugin.${xdoclet.plugin.namespace}.qtags</packagereplace>
                                        </params>
                                    </component>
                                    <component>
                                        <classname>org.xdoclet.plugin.qtags.doclipse.QTagDoclipsePlugin</classname>
                                        <params>
                                            <filereplace>qtags.xml</filereplace>
                                            <namespace>${xdoclet.plugin.namespace}</namespace>
                                        </params>
                                    </component>
                                    <component>
                                        <classname>org.xdoclet.plugin.qtags.confluence.QTagConfluencePlugin</classname>
                                        <params>
                                            <destdir>${project.build.directory}/tag-doc</destdir>
                                            <namespace>${xdoclet.plugin.namespace}</namespace>
                                            <filereplace>${xdoclet.plugin.namespace}.confluence</filereplace>
                                        </params>
                                    </component>
                                </components>
                                <includes>**/*.java</includes>
                                <!--
                                    common parameters for all used plugins.  individual plugins 
                                    can override them. 
                                --->
                                <params>
                                    <destdir>${project.build.directory}/generated-resources/xdoclet</destdir>
                                </params>
                            </config>
                        </configs>
                    </configuration>
                </plugin>
            </plugins>
    </build>

Note 1: all of this could potentially go to a parent pom's <pluginManagement> element. However, it seems MNG-1804@jira has not fixed this case, so you currently still need to specify the plugin dependencies in the child pom. See MNG-1703@jira

User Documentation

IDE Integration

Maven Integration

Plugins

Project Information

Developer Documentation

Feeds

Foreword

Installation

Stay up-to-date

Usage