Section 1.19. Creating a Project Web Site | Maven: A Developers Notebook (Developers Notebooks)

1.19. Creating a Project Web Site

Maven can create a project web page, with metrics and information about a project.

1.19.1. How do I do that?

To create a Maven project web site, use the Site plug-in by running the following Maven goal:

C:\dev\mavenbook\code\genapp\test-application> maven site

Running the Site plug-in will create the project's web site in the default site output directory: test-application/target/docs/index.html. If you load this HTML, you will see a site with a distinctive Maven look and feel. Figure 1-5 shows a sample of a lightly customized Maven web site complete with a custom organization logo and project logo. Instead of showing you a contrived web site, you can see the site of a project currently using Maven as a build systemJaxen.

Figure 1-5. Sample Maven project web site

Most Maven sites have a Project Documentation navigation section which provides links to information common to all Maven projects. Project Info contains information about the project, a list of the project mailing lists, and information about source control and issue tracking (you'll discover all this in Section 4.1). Content for the generated Maven web site is developed by creating and modifying XML markup in the xdocs directory. In Figure 1-5, the project contains five project-specific documents: Overview, FAQ, Releases, CVS Access, and Status. These documents are included in the left navigation bar because they are included in the xdocs/navigation.xml file. The xdocs directory is where Maven stores project-specific documentation in an XML XDoc format. Here are the contents of the navigation.xml document for Jaxen:

<?xml version="1.0" encoding="ISO-8859-1"?>    <project name="jaxen" repository="jaxen" href="http://jaxen.org">      <title>jaxen: universal java xpath engine</title>      <body>     <links>       <item name="The Werken Company" href="http://www.werken.com/"/>     </links>     <menu name="jaxen">       <item name="Overview" href="/index.html"/>       <item name="FAQ" href="/faq.html"/>       <item name="Releases" href="/releases.html"/>       <item name="CVS Access" href="/cvs-usage.html"/>       <item name="Status" href="/status.html"/>      </menu>    </body>    </project>

The links element puts a link to http://www.werken.com on the righthand side of the page, under the project logo, and the menu element contains items to appear in the lefthand navigation area. One of the files in the menu is xdocs/index.xml. Here are the abbreviated contents of the xdocs/index.xml file from Jaxen:

<?xml version="1.0"?> <document url="http://jaxen.org/index.xml">      <properties>     <author email="bob@eng.werken.com">bob mcwhirter</author>     <title>jaxen</title>   </properties>      <body>     <section name="News">       <p>         Added the slidedeck from my          <a href="/pdf/intro-slides.pdf">SD-West presentation</a>.       </p>       <p>         Check out these          <a href="http://dom4j.org/benchmarks/xpath/index.html">Performance         Benchmarks</a> comparing dom4j and Jaxen against Xerces and Xalan.       </p>     </section> [...] </document>

Once you've generated your project site, load target/docs/index.html in a browser to see your project's web site.

1.19.2. What about...

...the syntax of these files?

You can find more information about the syntax and format of the navigation.xml file in the Maven XDoc Plug-in FAQ (http://maven.apache.org/reference/plugins/xdoc/faq.html), and you can find more information about the format of individual pages at the Maven XDoc Plug-in page (http://maven.apache.org/reference/plugins/xdoc/index.html). This plug-in page also contains more instructions for customizing the output and behavior of the site generation plug-in.

See Section 4.1 for a more in-depth analysis of the various reports that can shed light on project activity and structure.