appear in their published site's "Project Reports" section of the
navbar. Users can now specify a <reports/> section in the POM that
specifies exactly which reports should be included in one's site. For
example:
<reports>
<report>maven-changelog-plugin</report>
<report>maven-junit-report-plugin</report>
<report>maven-javadoc-plugin</report>
<report>maven-jxr-plugin</report>
</reports>
This would only run the above four plugins when 'maven site' is invoked.
In addition, the navbar and the maven-reports document that is generated
will only contain links to the above specified reports. Please note,
that the order the reports are specified is the order in which they will
appear. Note: if you do not have a <reports/> section in the POM, you
will fallback to the standard behavior (which is predefined reports).
Lets talk about how this all works now. Previously, site.jsl in the
xdoc plugin contained a static set of reports that were included in the
navbar. This could not be changed by end users. In addition, we also
had a separate xdoc to maintain which contained a description of all of
the reports (this page is displayed when you click on 'Project Reports'
to expand that section of the navbar). Again, this was a static page.
Finally, a developer writing their own plugin which generated a report,
would have to submit patches for both of these files for their report to
be included when a 'maven site' was executed.
All of the above deficiencies have been corrected when using the new
<reports/> mechansim. There is a new protocol which plugin developers
should follow if their plugin generates a report. Their plugin's
plugin.jelly file should contain a gool like this (don't forget to
include the 'xmlns:doc="doc"' declaration as well):
<goal name="maven-changelog-plugin:register">
<doc:registerReport
name="Change Log"
link="changelog-report"
description="Report on the source control changelog."/>
</goal>
The above should be pretty self explanatory. The plugin developer
simply defines a 'name'. The 'name' is used in the navbar and in the
first column of the table in the auto-generated maven-reports file.
'link' is the relative link from the doc directory to the generated
report (without the extension). Finally, a 'description' should be used
to create a one line summary of the report's contents. This is used
when auto-generating the maven-reports document.
A plugin may define multiple reports if needed. For example, here is
the javadoc plugin example:
<goal name="maven-javadoc-plugin:register">
<j:if test="${sourcesPresent}">
<doc:registerReport
name="JavaDocs"
link="apidocs/index"
description="JavaDoc API documentation."/>
<doc:registerReport
name="JavaDoc Report"
link="javadoc"
description="Report on the generation of JavaDoc."/>
</j:if>
</goal>
Another important difference you'll notice above is that the conditional
tests of whether or not a report should appear is no longer part of
site.jsl. The logic of determining whether the report appears now lies
within the plugin that generates the report. Thus, in the above
example, only if sources are present, will the reports actually appear
in the navbar and maven-reports document.
So what happens when one types 'maven site'? Basically, for each
<report/> defined, maven will try to <attainGoal> on that report. The
goal runs as it normally does. The magic kicks in when the 'xdoc'
plugin is run (after all of the <reports/> have been run). The first
thing the xdoc plugin does is determine what reports should be included
in all of the documentation it generates. The report list (its really a
set) is generated when xdoc calls its own 'xdoc:register-reports' goal.
This goal looks at each <report/> defined in the POM and then calls
<attainGoal name="xyz:register"/> where "xyz" corresponds to the name
defined in the <report/>. This is where the new protocol is required.
If that goal does not exist, you will get an error from Jelly.
As each of the xyz:register goals are called, they invoke the
<doc:registerReport> tag (which is defined in the xdoc plugin), this tag
basically builds a set of hashtables. Each hashtable corresponds to a
report and contains a 'name', 'link', and 'description' entry. After
the completion of 'xdoc:register-reports' we now have a set in the xdoc
context called 'reports' which contains our descriptions of each report.
Site.jsl uses this to dynamically build up the navbar, and the
maven-reports document uses it to build the content of itself.
Phew! That was a long one. In summary, if you don't use <reports/>
nothing changes (at least it shouldn't), but in the future, if this
<reports/> thing works out, we will migrate users in this direction.
git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@112789 13f79535-47bb-0310-9956-ffa450edef68
