How to include goals & parameters in documentation for a maven plugin site

Question

It appears that that you can generate a standard documentation website (like this one) from a Maven plugin project. I tried executing mvn site in a plugin project but it doesn't generate the expected documentation (a page that shows the Mojo goals, parameters, etc.). Is there some other goal that must be invoked to generate these web pages? I'm using Maven v. 2.1.0.

Answer 1

In order to get the plugin documentation (goals, params, etc.) included in the site documentation, you need to add the following to the pom.xml

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

This adds a "Project Reports" link to the site menu, which shows the Maven plugin's equivalent of Javadoc.

Answer 2

Out of the box, mvn site should at least generate an index page (and leverage the name and the descriptionfrom the POM of your project) and a basic set of reports (About, Issue Tracking, Project Team, Dependencies, Project Plugins, Continuous Integration, Source Repository, Project License, Mailing Lists, Plugin Management, Project Summary).

If you want to customize the set of reports, you can configure the Maven Project Info Reports Plugin (in the reporting section) to include only the reports you want:

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <version>2.2</version>
        <reportSets>
          <reportSet>
            <reports>
              <report>dependencies</report>
              <report>project-team</report>
              <report>mailing-list</report>
              <report>cim</report>
              <report>issue-tracking</report>
              <report>license</report>
              <report>scm</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
      ...
    </plugins>
  </reporting>
  ...
</project>

If you want to customize the site, you'll need to provide a site descriptor (src/site/site.xml by default). In that case, you'll have to include a <menu ref="reports"/> entry for the above reports.

If you want to add content, you'll have to provide it using one of the supported format (e.g. APT, FML, XDoc). Most of time, APT is used nowadays.

Check the documentation of the Maven Site Plugin for more details.

Answer 3

It doesn't generate anything? That would be strange, it should at least build a very basic site with general information and a documentation of dependencies. maven siteis the correct call.

For additional documentations (javadoc, test reports, etc) you need to add more elements to the build file. Have a look at the surefire plugin documentation for some examples.

Answer 4

No, but your project should contain a specific structure as shown here.