You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by ka...@apache.org on 2003/01/31 22:13:38 UTC
cvs commit: jakarta-turbine-maven/xdocs/reference developer-guide.xml
kaz 2003/01/31 13:13:38
Modified: xdocs/reference developer-guide.xml
Log:
Started the developer's guide. In particular, I've described the
protocol that plugins writers are expected to follow in order to be
automatically included in a Maven-generated site (see my previous
commit message for the gory details).
Revision Changes Path
1.2 +150 -0 jakarta-turbine-maven/xdocs/reference/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/xdocs/reference/developer-guide.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- developer-guide.xml 23 Aug 2002 14:30:01 -0000 1.1
+++ developer-guide.xml 31 Jan 2003 21:13:38 -0000 1.2
@@ -4,12 +4,162 @@
<properties>
<title>Developer Guide</title>
<author email="jason@zenplex.com">Jason van Zyl</author>
+ <author email="pete-apache-dev@kazmier.com">Pete Kazmier</author>
</properties>
<body>
<section name="Developer Guide">
<p>
+ Welcome. If you are reading this page, you should be a
+ developer interested in contributing to Maven and/or writing
+ plugins for Maven. If you are simply a developer <b>using</b>
+ Maven for your own project, you are looking for the
+ <a href="user-guide.html">User Guide</a>. With that said, this
+ document contains various snippets of information that even
+ Maven developer should know.
</p>
+ </section>
+ <section name="Plugins">
+ <p>
+ Adding functionality to Maven is done through the Maven plugin
+ mechanism. Maven comes shipped with numerous plugins. Plugins
+ can be used to do virtually any task desired. For example, they
+ can generate reports, create and deploy software distributions,
+ run unit tests, and much much more. This section of the
+ document will (in the future) describe how to write a plugin;
+ however, in the meantime it contains snippets of information not
+ necessarily assembled in any paricular order, but of importance
+ for anyone writing a plugin.
+ </p>
+ <subsection name="Reporting Protocol">
+ <p>
+ If you are writing a plugin which generates output that you
+ want to be included on Maven generated sites, then you need to
+ adhere to a specific protocol. This protocol ensures that
+ your output will be automatically included on a Maven
+ generated site if a user has selected to run the report
+ associated with your plugin. Assuming this is true, a link
+ will be created in the "Project Reports" section of the
+ navigation bar that points to the output generated by your
+ plugin. In addition, an entry will be included in the
+ document that provides an overview of all Maven generated
+ reports (this is the page that a user sees when they click on
+ the "Project Reports" section of the navigation bar).
+ </p>
+ <p>
+ The protocol consists of two requirements, both of which
+ require the specification of a goal in your
+ <code>plugin.jelly</code> file. The first goal should be
+ called <code>maven-xyz-plugin:register</code>, where
+ <code>xyz</code> is the name of your plugin. This goal should
+ contain one or more <code>doc:registerReport</code>
+ tags. The following is an example is taken from the changelog
+ plugin included with Maven:
+ </p>
+ <source><![CDATA[
+ <goal name="maven-changelog-plugin:register">
+ <doc:registerReport
+ name="Change Log"
+ link="changelog-report"
+ description="Report on the source control changelog."/>
+ </goal>
+ ]]></source>
+ <p>
+ This goal is responsible for "registering" the report that is
+ generated by your plugin with the xdoc plugin (the plugin that
+ generates the docs). Note, you <b>must</b> include the
+ following in your xmlns declarations in order to use the
+ <code>doc:registerReport</code> tag:
+ <code>xmlns:doc="doc"</code>. The
+ <code>doc:registerReport</code> tag has three required
+ attributes:
+ </p>
+ <table>
+ <tr><th>Attribute</th><th>Value</th></tr>
+ <tr>
+ <td>name</td>
+ <td>
+ The is the name of your report. It is the name that will
+ be used in the navigation bar as well as the
+ auto-generated <code>maven-reports.xml</code> overview
+ document. The name should be unique to prevent name
+ collisions with other plugins.
+ </td>
+ </tr>
+ <tr>
+ <td>link</td>
+ <td>
+ This is a relative link to the output of your plugin but
+ does <b>not</b> contain an extension. The link is
+ relative from the root of the generated site. For
+ example, if you specify <code>changelog-report</code> then
+ your generated output should be located in the root of
+ your <code>target/docs</code> directory and called
+ <code>changelog-report.html</code>.
+ </td>
+ </tr>
+ <tr>
+ <td>description</td>
+ <td>
+ This should be a one line description of the output
+ produced by your plugin. It is included on the
+ auto-generated <code>maven-reports.xml</code> overview
+ document.
+ </td>
+ </tr>
+ </table>
+ <p>
+ A plugin may specify more than one report. It is entirely
+ possible to register additional reports as shown below (taken
+ from the javadoc plugin included with Maven):
+ </p>
+ <source><![CDATA[
+ <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>
+ ]]></source>
+ <p>
+ The above example registers two reports with the xdoc plugin.
+ A keen observer will notice that the above plugin does not
+ register its reports if the project does not have any sources.
+ It is encouraged that plugin developers use conditional logic
+ to prevent their reports from registering if they don't apply
+ to the user's project.
+ </p>
+ <p>
+ The second part of the plugin protocol is the specification of
+ a goal called <code>maven-xyz-plugin:report</code>, where
+ <code>xyz</code> is the name of your plugin. This goal must
+ generate the output for your plugin. For example, if you were
+ writing a plugin to generated javadoc (which you wouldn't
+ because it already exists), you would create a goal called
+ <code>maven-javadoc-plugin:report</code> and it would contain
+ the logic necessary to produce the resulting JavaDocs.
+ </p>
+ <p>
+ If you adhere to the following protocol, users will be able to
+ select which reports they want to be included in their
+ Maven-generated site by specifying a <code>reports</code>
+ section in their POM. For example, to include the javadoc and
+ changelog reports in a site, the POM would include the
+ following:
+ </p>
+ <source><![CDATA[
+ <reports>
+ <report>maven-changelog-plugin</report>
+ <report>maven-javadoc-plugin</report>
+ </reports>
+ ]]></source>
+ </subsection>
</section>
</body>
</document>
Re: cvs commit: jakarta-turbine-maven/xdocs/reference developer-guide.xml
Posted by Incze Lajos <in...@mail.matav.hu>.
On Fri, Jan 31, 2003 at 09:13:38PM +0000, kaz@apache.org wrote:
> kaz 2003/01/31 13:13:38
>
> Modified: xdocs/reference developer-guide.xml
> Log:
> Started the developer's guide. In particular, I've described the
> protocol that plugins writers are expected to follow in order to be
> automatically included in a Maven-generated site (see my previous
> commit message for the gory details).
>
Clearly, an angel.