Multi module POM - creating a site that works

StackOverflow https://stackoverflow.com/questions/10848715

  •  12-06-2021
  •  | 
  •  

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?

Was it helpful?

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

OTHER TIPS

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

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.

This doesn't work exactly how you would think it would. This is described in the Why don't the links between parent and child modules work when I run "mvn site"? FAQ.

I'm not an expert at Maven but this is how I got a site to generate locally:

  1. Configure a <site> in your root POM 

    <distributionManagement>
    <site>
        <id>internal.repo</id>
        <name>Temporary Staging Repository</name>
        <url>file://${project.build.directory}/mvn-repo</url>
    </site>
</distributionManagement>

  2. Build the site for your project

    mvn site

  3. Generate the local staging site. This "Deploys the generated site to a local staging or mock directory based on the site URL specified in the section of the POM."

    mvn site:stage

  4. By default, the site will be generated underneath the ${project.build.directory}/staging directory

Some pointers for the lost. After running mvn site site:stage the site directory will not contain the composed site, that will be in the staging directory. According to the maven site plugin usage page the composition is not done until the site is deployed. After staging, you can call mvn site:deploy to copy the composed site to the location specified in the url you defined in the distributionManagement 

<distributionManagement>
  <site>
    <id>website</id>
    <url>file://${project.build.directory}/completesite</url>
  </site>
</distributionManagement>

In this case the completed site will end up in the directory completesite in the project build directory (usually the target directory).

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.

At http://wiki.bitplan.com/index.php/Multi-Module_Maven_with_github_pages you'll find a detailed analysis and example in the context of github-pages. See also Multi-module example of using mvn site-deploy with github pages

Whats the work-around?

  • Do not use the plugin!
  • git clone or pull the gh-pages to a local folder
  • mvn site:stage to a temporary staging directory
  • rsync the results into the git local folder
  • check in the local folder

  • have a cup of coffee or drink a beer / be happy

    Do not use the plugin!

  • It's slow (as in really slow ... 18 minutes for the sample project)

  • It's not reliable (as in 500 HTML Codes)

  • It's not maintained well (as in [https://github.com/github/maven-plugins/issues 57 open issues as of 2018-08]

  • It's superflous (see below) Even the committer's don't use it any more (as in a personal mail I got today ..)
#
# createSite
#   ws: global variable pointing to workspace 
#   param 1: l_project - project name/directory
#   param 2: l_ghpages - directory where gh-pages branch has been git cloned/pulled
#   param 3: l_modules - non-empty for a multi-module project (e.g. containing the list of modules)
#
createSite() {
  local l_project="$1"
  local l_ghpages="$2"
  local l_modules="$3"

  color_msg $green "creating site for $l_project $l_modules"
  cd $ws/$l_project
    stage=/tmp/stage$$
    sitelog=/tmp/sitelog$$.txt
    rm -rf $stage
    # the stagingDirectory needs to be subdirectory 
    mkdir -p $stage/$l_project

    # run the staging of the site against this directory and log the results
    mvn -U clean install site site:stage -DstagingDirectory=$stage/$l_project | tee $sitelog

    # rsync the result into the github-pages folder
    rsync -avz --del $stage/* $l_ghpages/$l_project/

    # is this a multi module project?
    if [ "$l_modules" != "" ]
    then
        cd $l_ghpages/$l_project/
        if [ ! -f index.html ]
        then
cat << EOF > index.html
<!DOCTYPE html>
<html>
<head>
   <!-- HTML meta refresh URL redirection -->
   <meta http-equiv="refresh"
   content="0; url=./$l_project/$l_project/index.html">
</head>
<body>
   <p>This is a multimodule mvn site click below to get to the index.html of 
   <a href="./$l_project/$l_project/index.html">$l_project</a></p>
</body>
</html> 
EOF
        fi
        # add potentially new files
        git add *
        # commit results
        git commit -m "checked in by checksite script"
        # push results
        git push
    fi
    if [ "$debug" = "false" ]
    then
      rm -rf $stage
        rm $sitelog
    fi
}

I my case adding the below section to the top pom resolved the problem:

<distributionManagement>
  <site>
    <id>struts-site</id>
    <url>https://struts.apache.org/maven/</url>
  </site>
</distributionManagement>

Right now using the below command it will generate the whole page under target/staging:

./mvnw clean site site:stage

I'm using such plugin configuration:

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.9.0</version>
<configuration>
  <relativizeDecorationLinks>false</relativizeDecorationLinks>
</configuration>

Please be aware that you must also define site.xml for each submodule as menus are not inherited.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top