How to auto-generate Maven plugin documentation

This article assumes that you are familiar with writing maven plugins and describes how you can automatically generate your plugin documentation, and keep it in sync with the plugin code. It shows you how to automatically generate documentation on plugin goals, including documentation for command line or other optional parameters required by the plugin.

Changes to pom.xml

Add the maven-plugin plugin to the reporting section of your pom.

 <build>
 ...
 </build>

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

Add/modify your site.xml

Add/modify the following file, make sure to include the plugin-info.html file in the menu. This file is automatically generated from the javadoc comments in your plugin java code.

src/site/site.xml

Example site.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project name="My first plugin">
  <publishDate format="dd MMM yyyy" position="left"/>
  <body>
   <menu name="Overview">
      <item name="Introduction" href="index.html"/>
      <item name="Goals" href="plugin-info.html"/>
      <item name="FAQ" href="faq.html"/>
   </menu>
  </body>
</project>

Add the Indroduction page

Add the index.apt (almost plain text) file here:

src/site/apt/index.apt

Sample introduction page:

 ------
 Introduction
 ------
 ------

My first Maven Plugin

 Provides support for using my software with Maven 2.

* Goals Overview

 All the goals available in My First Maven Plugin can be found on the {{{usage.html}goals page}}.

 []

* Usage

 Instructions on how to use the Selenium Maven Plugin can be found on the {{{usage.html}usage page}}.

 []

Add a FAQ

Add the faq file here:

src/site/fml/faq.fml

Contents of the faq file:

<?xml version="1.0" encoding="UTF-8"?>
<faqs id="FAQ" title="Frequently Asked Questions">
  <part id="General">
    <faq id="question">
      <question>Type the question here</question>
      <answer>
        <p>
          Type the answer here
        </p>
      </answer>
    </faq>
  </part>
</faqs>

References

Maven plugin documentation guide

Vineet Manohar's blog

Archives

Java blogs

Meta