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

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

Answer 2

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.

Answer 3

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

Answer 4

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
}

Answer 5

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

Answer 6

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.