Maven can be used to generate an entire web site for your project. The web site can be used to house all of your user-facing documentation, generated as flat HTML with a common look and feel.
It also contains a number of generated documents based on the information in your project. This can include SCM information, mailing lists and a list of developers, as well as FAQs and release notes based on additional metadata you provide.
Finally, the web site will contain various reports about your source code generated by the plugins included in Maven such as javadocs, metrics, unit test results, changelogs, and more.
To add documents to the site, first you will need to add them to the navigation so that they can be found.
To do this, create a navigation.xml file in the xdocs directory that contains the
menu structure for the entire document tree. Add all items and sub-items.
For items that can collapse when you are not browsing them, add
collapse="true"
to the item declaration.
The following is an example navigation.xml file:
PDF Documentation
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Maven xdoc Plugin">
<!-- Page Title -->
<title>Maven xdoc Plugin</title>
<body>
<!-- Links defined across the top right of the site -->
<links>
<item name="Maven" href="http://maven.apache.org/"/>
</links>
<!-- Menu in the Left Navigation -->
<menu name="Menu Name">
<!-- Standalone item -->
<item name="Item" href="/item.html" />
<!-- Uncollapsed Submenu -->
<item name="Alpha" href="/alpha/index.html">
<item name="Alpha One" href="/alpha/one/index.html"/>
<item name="Alpha Two" href="/alpha/two/index.html"/>
</item>
<!-- Collapsed Submenu -->
<item name="Beta" href="/beta/index.html" collapse="true">
<item name="Beta One" href="/beta/one/index.html" collapse="true"/>
<item name="Beta Two" href="/beta/two/index.html" collapse="true"/>
</item>
</menu>
</body>
</project>
Note: the href element should be absolute, referenced according to your document root
(ie, under xdocs).
You can also add images to items in the menu, for example:
<item name="The Site" href="http://www.thesite.net/" img="http://www.thesite.net/thesite.png"/>
The XDoc format is quite simple, and is based on the original Anakia format that originated in Jakarta. The following is a sample XDoc document:
<document>
<properties>
<author email="user@company.com">John Doe</author>
<title>Page Title</title>
</properties>
<!-- Optional HEAD element, which is copied as is into the XHTML <head> element -->
<head>
<meta ... />
</head>
<body>
<!-- The body of the document contains a number of sections -->
<section name="section 1">
<!-- Within sections, any XHTML can be used -->
<p>Hi!</p>
<!-- in addition to XHTML, any number of subsections can be within a section -->
<subsection name="subsection 1">
<p>Subsection!</p>
</subsection>
</section>
<section name="other section">
<!-- You can also include preformatted source blocks in the document -->
<source>
code line 1
code line 2
</source>
</section>
</body>
</document>
To create one of these documents, create an XML file in the directory structure you want for your site under
the xdocs document root. For example, /start/introduction.xml will be generated as
/start/introduction.html on the final site.
The following sections give some details on specific customisations you might want to make to the generated site.
For more information on customising the generated site, see the XDoc plugin reference.
Maven will generate a default index.html page for your project based on the
description element in the POM. However, this is usually not very verbose, so you may like to
create your own index page.
To do this, simply create an index.xml document in the base xdocs directory in the
same style as the other documents (as explained in the previous sections), and this will be used instead of
the generated document.
By default, all Maven-generated sites use the same look and feel for consistency. This enables users to easily recognize a Maven-generated site and immediately feel comfortable searching for information on the site.
Of course, we understand that users will want to customize their own sites. There are two alternatives.
Firstly, you can select different skins. Currently Maven comes with two skins - the current default and the "classic" skin that appeared in Maven 1.0 Beta 10 and earlier. Selection of the skin (and the colours used if using the classic skin) is done through properties given to the XDoc plugin.
The other alternative is to provide your own CSS. The Maven site is generated in XHTML and the layout defined
by CSS. The best alternative is to take the existing stylesheet and modify it according to your tastes.
To specify the alternate stylesheet, set the maven.xdoc.theme.url property for the XDoc plugin
(again, see the properties for more information).
Finally, if you want to customize which reports are
automatically generated for your site, you need to include the
reports tag
in your project descriptor. This tag enables you to
selectively choose which reports to include and exclude as
well as the order of the reports.
The following are the default set of reports, as specified by the XDoc plugin:
maven-changelog-plugin maven-changes-plugin maven-checkstyle-plugin maven-developer-activity-plugin maven-file-activity-plugin maven-javadoc-plugin maven-jdepend-plugin maven-junit-report-plugin maven-jxr-plugin maven-license-plugin maven-linkcheck-plugin maven-pmd-plugin maven-tasklist-plugin
Users building documentation-only sites or sites that
aggregate a lot of sub-projects might want to prevent the
inclusion of the entire "Project Documentation" section of the
navigation bar on their sites. This can be done by setting
the
maven.xdoc.includeProjectDocumentation
property to the value of
no. By default, Maven
will include the "Project Documentation" section of the
navigation bar which includes information about the project as
well as links to the numerous Maven-generated reports.