Multi module POM - creating a site that works

OK, finally got this working.

Add this (only) to the parent POM, changing staging folder as required:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.0</version>
    <configuration>
     <stagingDirectory>C:\temp\stage</stagingDirectory>
     <reportPlugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-project-info-reports-plugin</artifactId>
         <version>2.4</version>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>2.8</version>
         <configuration></configuration>
         <reportSets>
           <reportSet>
             <id>non-aggregate</id>
             <configuration>
               <!-- Specific configuration for the aggregate report -->
               <sourcepath>${project.build.sourceDirectory}/../generated</sourcepath>
             </configuration>
             <reports>
               <report>javadoc</report>
             </reports>
           </reportSet>
           <reportSet>
             <id>aggregate</id>
             <configuration>
               <!-- Specific configuration for the aggregate report -->
               <sourcepath>${project.build.sourceDirectory}/../generated</sourcepath>
             </configuration>
             <reports>
               <report>aggregate</report>
             </reports>
           </reportSet>
         </reportSets>
       </plugin>
        <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-report-plugin</artifactId>
         <version>2.6</version>
       </plugin>
     </reportPlugins>
    </configuration>
</plugin>

Add this to distribution management section of the parent:

<site>
  <id>${project.artifactId}-site</id>
  <url>./</url>
</site>

Then run

mvn site site:stage

This should deploy into temp/site with working links.

I found a "simpler" solution to configure the stage goal. It will automatically aggregate the documentation of each module in the ${project.baseURI}/target/staging folder. The trick is to add this to the parent pom of all the sub-modules:

  <distributionManagement>
     <site>
        <id>${project.artifactId}-site</id>
        <url>${project.baseUri}</url>
     </site>
  </distributionManagement>

Run

mvn clean site site:stage 

from the pom aggregator. Then have a look in the target/staging folder. You will have the sub-modules documentation correctly linked!

It's over a year now since the last solution.

I did not like this workaround, there has to be another solution "the maven way".

So here it is:

In the Maven Site Plugin FAQ: http://maven.apache.org/plugins/maven-site-plugin/faq.html#Use_of_url

"On the other hand, the is used in a multi-module build to construct relative links [...]. In a multi module build it is important for the parent and child modules to have different URLs."

You must declare the <distributionManagement> tag in every pom.xml with different URLs:

Parent POM:

<distributionManagement>
  <site>
    <id>mysite</id>
    <name>My Site</name>
    <url>ftp://server.example.com/htdocs/site/</url>
  </site>
</distributionManagement>

Child One POM:

<distributionManagement>
  <site>
    <id>mysite</id>
    <name>My Site</name>
    <url>ftp://server.example.com/htdocs/site/one/</url>
  </site>
</distributionManagement>

Child Two POM:

<distributionManagement>
  <site>
    <id>mysite</id>
    <name>My Site</name>
    <url>ftp://server.example.com/htdocs/site/two/</url>
  </site>
</distributionManagement>

Now the generation of the site, and the staging works as requested. The staged site is generated in parent/target/staging

You can submit another staging directory with -D

mvn -DstagingDirectory=D:/Temp/Site package site site:stage

Note: goal package is needed, if child two has child one as dependency. With package, the goal site is executed without the error that a dependency is missing in the repository.

Edit: It is necessary to provide a <url> for each artifact that uses the same pathes as in the <distributionManagement>. This is, because the index.html generated with the report-info-plugin uses the <url> to calculate relative pathes, but the site:stage uses the <distributionManagement>.