Multi module POM - creating a site that works

Question

I have a multi module application, and I’m trying to generate a Maven site for this app.

I have an aggregating POM that holds all the child modules, an inheritance POM that holds all the common features for the child modules, and a 20 or so child modules.

I have cycled through endless online examples of how to get this to work. In none of these does the multi module part of this work. I can get the individual site output built OK, in the target/site folder of the children (and the aggregating module). I’ve also had it staging into a target/staging folder in the aggregating POM. The created stuff looks good.

But:

None of the child module links work.

I’ve tried running this under jetty, as some comments on this problem say the links only work when it’s built as a web site – but no, same problem, it can’t find the index.html of the child.

Does anyone have an example of this working? And to avoid me tearing out any more hair (god knows it’s running out up there as it is) I’d rather see the actual working POM code and/or the stages followed to correct test and deploy.

Can anyone help?

Answer 1

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!

Answer 2

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.

Answer 3

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>.