Maven project site guide

Maven creates most of its site content on it's own. This behavior is controlled by reporting plugins.

Reporting plugins

These reporting plugins are defined in the parent pom of each project.

Here you can see a sample report entry for the javadoc documentation:

<reporting>
        <plugins>
		<plugin>
			<artifactId>maven-javadoc-plugin</artifactId>
		</plugin>
	...

This simple entry in the pom creates the whole documentation page and automatically links it in the root project page. If you want to have a new reporting feature, just add the module in the parent pom and every submodule will derive from it.

If you want to add a custom page to the generated ones, this can easily be done.

Create a custom page

The source code of the html files are kept in the svn repository together with the other resources (java src.) of the project. So if you want add a page you have to checkout the source files of the project. An explanation to get the sources and to get maven can be found in the Installation of maven guide.

In every project you can see the following directory structure:

   +- src/
   +- site/
      +- apt/
      |  +- index.apt
      |
      +- xdoc/
      |  +- other.xml
      |
      +- fml/
      |  +- general.fml
      |  +- faq.fml
      |
      +- site.xml

You can see the site descriptor site.xml and all the custom pages separated by the supported doc formats. These are:

• apt ("Almost plain text") is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. Reference lies here.
• xdoc is a xml documentation system, defined by maven. The reference can be found here.
• fml is mainly used for creating FAQs. An example is here

The site descriptor defines how the created pages are included in the project page. A good HowTo on defining a site descriptor and can be found here

So for creating a page, you would

• first create the page in the desired format

+- site/
      +- xdoc/
      |  +- new_folder/
             +- new_page.xml

• and then define it in the site descriptor site.xml

 <menu name="Sample menu">
      <item name="Sample page" href="new_folder/new_page.html"/>
    </menu>