maven - 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!