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
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>
Maven can use additional plugins for a clear and helpful documentation of code and project specific information. Some very useful plugins are presented here.
The Javadoc plugin searches for Javadoc comments within the code of the project and generates the corresponding javadocs. Information can be found here.
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.
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.
To build the Maven project site (the one you are just looking at right now), use:
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