Overview

  • Generation

Project Documentation

Documentation Writing

The prefered documentation format for OW2 Utilities sites is markdown. Markdown support is automatically enabled when inheriting from org.ow2.util:parent.

Markdown's files are in the src/site/markdown directory (or subdirs) and are ending with the .md extension. It's possible to append a trailing .vm in order to enable content filtering (the page becomes a Velocity template page).

See Markdown's site for details about syntax.

Site Generation (default)

A default set of reporting plugins is enabled by the inherited org.ow2.util:parent POM. Details on default configurations can be found below.

The parent POM set a default version for each reporting plugin with a property named after the following template: ${plugin.artifactId}.version. Each project can select a different version by overriding that property or simply specifying the plugin's version in the plugin's declaration.

Selection and configuration of reporting plugins is done in the project/reporting/plugins section of the POM.

Each plugin can decide to enable or disable the set reports that will be generated and aggregated into its site. Disabling all reports for a given plugin can be done easily, just select an empty set of report:

<reportSets>
  <reportSet></reportSet>
</reportSets>

Project Information Report

Generates reports information about the project. All reports are enabled by default.

Latest version and available reports can be found on the plugin's official page.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-project-info-reports-plugin</artifactId>
</plugin>

Javadoc Report

Generates Javadoc. Notice that reactor modules have their sub-modules's Javadoc automatically aggregated.

Latest version and available reports can be found on the plugin's official page.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
</plugin>

JIRA Report

Generates a JIRA report for the current version.

Latest version and available reports can be found on the plugin's official page.

Default configuration

Default's value of jira.component property is ${project.artifactId}. It can be overriden with a project's property.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <configuration>
    <component>${jira.component}</component>
    <onlyCurrentVersion>true</onlyCurrentVersion>
    <versionPrefix>${jira.component}-</versionPrefix>
    <runOnlyAtExecutionRoot>true</runOnlyAtExecutionRoot>
  </configuration>
  <reportSets>
    <reportSet></reportSet>
  </reportSets>
</plugin>

Report's activation

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <reportSets>
    <reportSet>
      <reports>
        <report>jira-report</report>
      </reports>
    </reportSet>
  </reportSets>
</plugin>

Surefire Report

Generates test reports pages.

Latest version and available reports can be found on the plugin's official page.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-report-plugin</artifactId>
  <reportSets>
    <reportSet>
      <reports><report>report</report></reports>
    </reportSet>
  </reportSets>
</plugin>

Changelog Reports

Generates a changelog page and SCM activity pages (per file and per author).

By default, it is configured to hook into Gitorious' webview (expecting the module's repository name to be ${project.artifactId}).

Latest version and available reports can be found on the plugin's official page.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changelog-plugin</artifactId>
  <configuration>
    <displayFileDetailUrl>http://gitorious.ow2.org/ow2-utilities/${project.artifactId}/blobs/master/%FILE%</displayFileDetailUrl>
  </configuration>
</plugin>

Source Report

Generates Source XRef pages (and Test Source XRef).

Latest version and available reports can be found on the plugin's official page.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jxr-plugin</artifactId>
</plugin>

Plugin Site Generation

Maven Plugin Report

This plugin is not activated by default in the OW2 utilities parent POM (all projects are not plugins).

Generates Maven Plugin's goals pages.

Latest version and available reports can be found on the plugin's official page.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-plugin-plugin</artifactId>
</plugin>

Do not forget to include the following XML fragment into your src/site/site.xml to ease navigation to the interestings bits of documentation:

<menu name="Overview">
  [ ... ]
  <item name="Goals" title="Goals" href="./plugin-info.html" />
  [ ... ]
</menu>

Resources