<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 -->

<document>

  <properties>
    <title>Maven Dashboard plugin</title>
    <author email="vmassol@apache.org">Vincent Massol</author>
  </properties>

  <body>
    <section name="Maven Dashboard plugin">
      <p>
        Generate a dashboard HTML report containing information gathered 
        from other Maven reports (Checkstyle, Clover, JUnit, Simian, etc).
        The dashboard aggregate this information for all subprojects, 
        presenting them in a single tabular format.
      </p>
      <p>
        Please note that the dashboard plugin is not supposed to work on a
        single project. You need to have a master project and subprojects to
        make it work.
      </p>      
      <p>
      	Current features:
      </p>
      <ul>
        <li>
          Pluggable architecture. It allows to add custom aggregators for any
          kind of report, be them Maven reports or anything else (like 
          calling an SCM system, calling JIRA, etc). An aggregator is actually 
          a Jelly script so that you have the full power of Jelly at your hand.
        </li>
        <li>
          Provides <a href="aggregators.html">default aggregators</a>.
        </li>
        <li>
          Allows tight integration in one's own custom reactor and prevents
          running reports several times.
        </li>
      </ul>
    </section>
    <section name="Quick start">
      <p>
        There are several possible ways of using the dashboard plugin.
      </p>
      <subsection name="Solution 1: Registering it as a Maven report">
        <p>
          In your master project, add a <code>maven-dashboard-report</code>
          report entry:
        </p>
<source><![CDATA[
  <reports>
    [...]
    <report>maven-dashboard-plugin</report>
  </reports>
]]></source>
        <p>
          Then, when you generate the web site (<code>maven site</code>),
          Maven will generate the dashboard report which will be available
          in the web site left menu, under "Project Reports".
        </p>
      </subsection>
      <subsection name="Solution 2: Running it manually">
        <p>
          In your master project, simply type <code>maven dashboard</code>.
          This will generate a dashboard xdoc file. Then type
          <code>maven xdoc</code> to transform it into an HTML file.
        </p>
      </subsection>
      <subsection name="Solution 3: Using the multiproject plugin">
        <p>
          In your master project, add a <code>maven-dashboard-report</code>
          report entry:
        </p>
<source><![CDATA[
  <reports>
    [...]
    <report>maven-dashboard-plugin</report>
  </reports>
]]></source>
        <p>
          Add the following 3 properties to your master project:
        </p>
<source><![CDATA[
# Tells the dashboard plugin not to run its own reactor. 
# We'll use the one run by the multiproject.
maven.dashboard.runreactor = false

# (optional). Tells the dashboard not to specifically run 
# artifact goals (i.e. goals that generate artifacts that we aggregate
# in the dashboard report). For example, if you already have defined
# the reports generating these artifacts, you'd be better setting
# rungoals to false so that the artifact goals are only run once.
maven.dashboard.rungoals = false

# Tells the multiproject plugin to execute the dashboard:report-single
# goal on each project when you run it through multiproject:site.
maven.multiproject.site.goals=site,dashboard:report-single
]]></source>
        <p>
          Then generate the site by running the  <code>multiproject:site</code>
          goal.
        </p>
        
      </subsection>
    </section>
 </body>
</document>
