When running mvn site on a top level project, Maven will build all sites for every module defined in the modules section of the pom individually. Note that each site is generated in each individual project's target location. As a result, relative links between different modules will NOT work. They will however work when you deploy or stage the site.
To preview the whole tree of a multi-module site, you can use the site:stage goal. This will copy individual sites to their proper place at the staging location.
site:deploy does the same thing as site:stage, but uses the url defined in the <distributionManagement> element of the pom as deployment location. This is usually a remote url, but both remote protocols like scp and local protocols like file are supported.
Finally, site:stage-deploy does the same thing as site:deploy but uses the stagingDirectory parameter as deployment location. This can be used to deploy the site to a remote staging area (site:stage is always local).
Site descriptors are inherited along the same lines as project descriptors are. If you want your project's site descriptor to be inherited, you need to attach it to the project's main artifact. You use the site:attach-descriptor goal to attach the site descriptor to your project's main artifact.
In Maven 3 you must attach the site descriptor yourself, even for projects with packaging set to "pom".
By default, all the parent descriptor settings are inherited with the only exception of menus, see below. From the body, the links and breadcrumbs accumulate to contain all the parent's site descriptor links and breadcrumbs. If the parent contains some breadcrumb and the inheriting site descriptor doesn't, a breadcrumb with the current site descriptor's name will be added automatically.
However, it is possible to inherit menus as well. To do so, use the inherit attribute in the site descriptor. This can be either top or bottom, indicating where the inherited menu will be placed. For example:
<project> ... <body> ... <menu name="My Inherited Menu" inherit="top"> ... </menu> ... </body> ... </project>
Some reports can be run against the sum of every modules: these are aggregate reports. This is the case of maven-javadoc-plugin, maven-jxr-plugin or maven-checkstyle-plugin.
To benefit from aggregate reports, you must configure a reportSet in the parent pom, and turn inheritance off to avoid the aggregate report to be run in modules. For example, with maven-jxr-report:
<project> ... <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jxr-plugin</artifactId> <version>2.3</version> <reportSets> <reportSet> <id>aggregate</id> <inherited>false</inherited> <reports> <report>aggregate</report> </reports> </reportSet> </reportSets> </plugin> </plugins> </reporting> ... </project>