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 PO

Answer 1

The child links will not work within your current project you need to do a site:stage otherwise it will not work. You need to define the stagingDirectory which defines the target location which must be an absolute path.

Answer 2

I have a similar case to the OP, with a twist: one of the child modules does not inherit from the multi-module project parent. I wanted to generate a staged site that had all of the links working correctly. Here's the project structure:

extraParent     // parent not part of this multi-module build
foo
  pom.xml       // aggregator
  fooParent     // parent for this project
  module1       // inherits from fooParent
  extraModule   // inherits from extraParent

@Stefan's answer was a great step in the right direction. In particular, I confirmed that the child modules MUST repeat both the distributionManagement and url elements. I tried this in fooParent:

<properties>
  <foo.site.url>file://somePath/foo/${project.artifactId}</foo.site.url>
</properties>

<url>${foo.site.url}</url>
<distributionManagement>
    <site>
        <id>site-docs</id>
        <url>${foo.site.url}</url>
    </site>
</distributionManagement>

Maven calculated correct values for foo.site.url in fooParent and module1: file://somePath/foo/fooParent and file://somePath/foo/module1 respectively. Yet, the top level site does not contain correct links to module1 unless the exact same url/distributionManagement blocks are duplicated in the child. It appears that the site generation is checking for inherited configuration without considering the actual URL values (even though they are different in the case described when I look at the effective POMs). I found this to be very non-intuitive.

I needed one more config element to get the top level site to link in extraModule correctly: topSiteURL. I added the following to extraModule's POM. Note I just extracted the base part of the URL (including the top level directory) into the topSiteURL value and then used it in the foo.site.url property.

<properties>
  <topSiteURL>file://somePath/foo/</topSiteURL>
  <foo.site.url>${topSiteURL}/${project.artifactId}</foo.site.url>
</properties>

<url>${foo.site.url}</url>
<distributionManagement>
    <site>
        <id>site-docs</id>
        <url>${foo.site.url}</url>
    </site>
</distributionManagement>

Now when I generate the site for the multi-module project with mvn site site:stage, all the links work.

Answer 3

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!