Technology: Maven Site

Creating the Site structure

This section shows how to create and configure the documentation for a project with Maven Site.


Open a console windows and go to the parent directory of the project created before. Type and run the following (Notice that the values for groupId and artifactId are the same as before):

mvn archetype:generate 
-DarchetypeGroupId=org.apache.maven.archetypes 
-DarchetypeArtifactId=maven-archetype-site 
-DgroupId=com.mycompany.app 
-DartifactId=documentation			
				

The command will change the directory structure of your project to the following:

my-app
|- src
|  |- main
|  |  `- java
|  |     `- com
|  |        `- mycompany
|  |           `- app
|  |              `- App.java
|  |- site
|  |  |- apt
|  |  |  |- format.apt
|  |  |  `- index.apt
|  |  |- fml
|  |  |  `- faq.fml
|  |  |- fr
|  |  |  `- ...
|  |  |- xdoc
|  |  |  `- xdoc.xml
|  |  |- site.xml
|  |  `- site_fr.xml
|  `- test
|     `- java
|        `- com
|           `- mycompany
|              `- app
|                 `- AppTest.java
`- pom.xml				
				
  • The directory fr and file site_fr.xml are for doumentation in French and can be deleted, if you don't want to document in French.
  • The other directories and files are used for documentation with different file formats and syntax.
    • apt is a Wiki like format that should mainly be used for documentation.
    • fml is a format to structure FAQs.
    • xdoc is a XML like format that is widely replaced by apt
  • As mentioned before external files can also be used within the documentation. Therefore you have to create a new folder resources in the site directory. The example shows an apt file with references to some resources.

Configuring the menu of the documentation

To configure the structure of the menu the file site.xml from the site directory must be edited. The structure of the menu from the basic example could be used as a template. Generally the structure of the menu looks like this:

<menu name="Hierarchy 1">
    <item name="Hierarchy 2" href="test.html"  />
    <item name="Hierarchy 2" href="team-list.html">
	  <item name="Hierarchy 3" href="test.html" />
    </item>
</menu>				
				
  • Automatically generated reports can be included with the entry <menu ref="reports" />.
  • References to parent or child projects (that must be defined in the POM) can be made with <menu ref="parent" /> or <menu ref="modules" />.

Reporting with Maven Site

Maven can use additional plugins for a clear and helpful documentation of code and project specific information. Some very useful plugins are presented here.

Javadoc

The Javadoc plugin searches for Javadoc comments within the code of the project and generates the corresponding javadocs. Information can be found here.

Surefire Reports

When using the Surefire plugin all available JUnit tests within the project are executed and then combined to a report that shows errors and the particular reason. By this the responsible developers can get an error overview without even touching an IDE. For further information be refered to the following site.

JXR plugin

The JXR plugin links a source code reference of the classes to the documentation which can be used very quickly to find important passages of program code. More information here.

Building the site

To build the Maven project site (the one you are just looking at right now), use:

mvn site

This creates a directory target\site where all html files can be found that represent the documentation. If the project got some further modules that should also be included into the documentation, use:

mvn site:stage -DstagingDirectory=path/to/directory/of/choice

Reference