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

  1. Maven plugin documentation guide

Related posts:

  1. Tweet your builds with Maven Twitter Plugin
  2. The plugin ‘org.codehaus.mojo:selenium-maven-plugin’ does not exist or no valid version could be found
  3. Maven Cargo JBoss
  4. Maven Docbook for beginners
  5. 3 ways to run Java main from Maven

1 comment to How to auto-generate Maven plugin documentation

Leave a Reply

 

 

 

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Get Adobe Flash playerPlugin by wpburn.com wordpress themes