Table of Contents
Abstract
This chapter describes how to write and to check site documentation for any of the sister projects. Follow the steps in this chapter if you intend to contribute back to the sister projects and will be writing such documentation. There's no need to perform these steps if you are just building the sister projects from source.
Maven provides the ability to automatically create a website holding various reports, such as Checkstyle, PMD, test results and code coverage.
The reporting plugins in the corporate POM (see Chapter 6, Using the Corporate POM) go a long way to defining the contents of these sites; since every sister project uses the corporate POM that also means that the sites will have the same general contents.
Maven sites can also be customized and supplemented with additional details. This chapter describes how to perform this customization and where to place this documentation. It also describes how the sister project site should be skinned using a standard Maven skin, common for all sister projects. This chapter assumes that the Maven skin has been released (as described in Chapter 13, The Maven Skin).
Customization for Maven sites is accomplished by:
customizing the menu bar and general look-n-feel (see Section 8.3, “Customizing the Site Descriptor (site.xml)”)
This is done by editing the site descriptor for each module,
namely, src/site/site.xml. The exact content
of the site descriptor varies, generally parent modules (and
standalone modules) will have more content than child modules.
This is in part because child modules inherit certain information
from the parent.
writing additional site content (see Section 8.4, “Writing Additional Site Content”)
The additional content lives under
src/site/xxx, where xxx
represents the file format. These files can be linked to from the
menu bar using site.xml. Any document that
corresponds to index.html (for example
src/site/apt/index.apt) need not be
explicitly linked to because it will be the default for the
site.
specifying the list of reports to produce (see Section 8.5, “Generated Reports”)
This is done in the pom.xml. For sister
projects the configuration is inherited from the corporate
POM.
The following sections provide further detail on these steps.
For details on actually building, checking and deploying the site, see Chapter 11, Deploying the Site.