Difference between revisions of "Multi-Module Maven with github pages"

From BITPlan Wiki
Jump to navigation Jump to search
 
(54 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
* [https://github.com/BITPlan/com.bitplan.simplegraph/issues/18 Module results are not deployed to maven repository]
 
* [https://github.com/BITPlan/com.bitplan.simplegraph/issues/18 Module results are not deployed to maven repository]
 
led to the creation of the example project:
 
led to the creation of the example project:
−
* https://github.com/BITPlan/com.bitplan.multimodule
+
* https://github.com/BITPlan/com.bitplan.multimodule which uses
 +
* https://github.com/BITPlan/com.bitplan.pom for the [https://github.com/BITPlan/com.bitplan.pom/blob/master/pom.xml parent pom definition]
 +
in which the [https://github.com/github/maven-plugins github maven site plugin] is defined with the configuration
 +
<source lang='xml'>
 +
<!-- git hub site plugin https://github.com/github/maven-plugins -->
 +
<plugin>
 +
  <groupId>com.github.github</groupId>
 +
  <artifactId>site-maven-plugin</artifactId>
 +
  <version>${site-maven-plugin.version}</version>
 +
  <configuration>
 +
    <message>Creating site for ${github.owner} ${github.project}
 +
      ${project.version}</message>
 +
    <repositoryName>${github.project}</repositoryName>      <!-- github repo name -->
 +
    <repositoryOwner>${github.owner}</repositoryOwner>    <!-- github username -->
 +
  </configuration>
 +
  <executions>
 +
    <execution>
 +
      <goals>
 +
        <goal>site</goal>
 +
      </goals>
 +
      <phase>site</phase>
 +
    </execution>
 +
  </executions>
 +
</plugin>
 +
</source>
 +
 
 +
Following the suggestion of https://stackoverflow.com/a/19336536/1497139 led to adding
 
<source lang='xml'>
 
<source lang='xml'>
 
   <distributionManagement>
 
   <distributionManagement>
Line 12: Line 38:
 
     </site>
 
     </site>
 
   </distributionManagement>
 
   </distributionManagement>
 +
</source>
 +
to the parent pom.xml
 +
<source lang='bash'>
 +
mvn clean site
 +
... wait a long while ...
 +
 +
[INFO] Multi-Module ....................................... SUCCESS [04:22 min]
 +
[INFO] Multi-Module 1 ..................................... SUCCESS [04:09 min]
 +
[INFO] Multi-Module 2 ..................................... SUCCESS [04:09 min]
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] BUILD SUCCESS
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] Total time: 12:42 min
 +
</source>
 +
and you end up with Module 2 overriding the results of the Multi-Module and Module 1 results
 +
== Is it a bug or a feature? ==
 +
* [https://github.com/github/maven-plugins/issues/22 Its a bug!]
 +
== 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 {{Done}}
 +
=== Do not use the plugin! ===
 +
# It's slow (as in really slow ...)
 +
# 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 ..)
 +
=== Steps to work around ===
 +
==== git clone or pull the gh-pages to a local folder ====
 +
<source lang='bash'>
 +
git clone https://github.com/$owner/$project --branch gh-pages --single-branch
 +
</source>
 +
 +
==== mvn site:stage to a temporary staging directory ====
 +
<source lang='bash'>
 +
mkdir -p /tmp/stage/4site
 +
mvn -U clean install site site:stage -DstagingDirectory=/tmp/stage/4site
 +
[INFO] --- maven-site-plugin:3.7.1:stage (default-cli) @ multimodule2 ---
 +
[INFO] Using this base directory for staging: /tmp/stage/4site
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] Reactor Summary:
 +
[INFO]
 +
[INFO] Multi-Module ....................................... SUCCESS [  5.423 s]
 +
[INFO] Multi-Module 1 ..................................... SUCCESS [  4.043 s]
 +
[INFO] Multi-Module 2 ..................................... SUCCESS [  3.393 s]
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] BUILD SUCCESS
 +
[INFO] ------------------------------------------------------------------------
 +
[INFO] Total time: 13.665 s
 +
</source>
 +
'''Yes - thats right seconds not minutes!'''
 +
==== rsync the results into the git local folder ====
 +
<source lang='bash'>
 +
rsync -avz /tmp/stage/com.bitplan.multimodule/* $ghpages/com.bitplan.multimodule
 +
</source>
 +
=== check in the local folder ===
 +
in the $gphages/com.bitplan.multimodule folder:
 +
<source lang='bash'>
 +
git add *
 +
git commit -m "checking new site in ..."
 +
git push
 
</source>
 
</source>
 +
 +
=== have a cup of coffee or drink a beer / be happy {{Done}} ===
 +
{{Icon|name=coffee|size=128}}
 +
{{Icon|name=beer|size=128}}
 +
{{Icon|name=smile-o|size=128}}
 +
== gist of a script ==
 +
The following bash createSite function does the core work. To call it set the globals ws variable to your workspace and supply the three arguments e.g.
 +
<source lang='bash'>
 +
createSite com.bitplan.multimodule $HOME/Documents/gh-pages "multimodule1 multimodule2"
 +
</source>
 +
see the comments of the function below for the description of the three arguments.
 +
=== createSite bash function ===
 +
<source lang='bash'>
 +
#
 +
# 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
 +
}
 +
</source>
 +
== Speed comparison ==
 +
On my computer the plugin takes 18 minutes for the simple com.bitplan.multimodule example
 +
 +
The script needs 25 seconds!
 +
 +
= Aggregating Reports =
 +
The [https://stackoverflow.com/a/1276317/1497139 most highly rated answer] of
 +
* https://stackoverflow.com/questions/1274523/maven-surefire-reporting-plugin-configuration
 +
suggests
 +
<source lang='xml'>
 +
<reporting>
 +
  <plugins>
 +
    <plugin>
 +
      <groupId>org.apache.maven.plugins</groupId>
 +
      <artifactId>maven-surefire-report-plugin</artifactId>
 +
      <version>2.4.2</version>
 +
      <configuration>
 +
        <aggregate>true</aggregate>
 +
        <!--also set this to link to generated source reports-->
 +
        <linkXRef>true</linkXRef>
 +
      </configuration>
 +
    </plugin>
 +
  </plugins>
 +
</reporting>
 +
</source>
 +
while https://maven.apache.org/plugins/maven-site-plugin/examples/configuring-reports.html
 +
suggest that you need different reportsets depending on inherited/non inherited pom configurations
 +
* http://bartswennenhuis.nl/maven-aggregate-reports-for-multi-module-projects/
 +
describes details of aggregating. Especially that you have to run the mvn site command twice:
 +
<source lang=bash'>
 +
mvn verify site
 +
mvn site:site site:stage
 +
</source>
 +
to get an [https://bitplan.github.io/com.bitplan.multimodule/com.bitplan.multimodule/com.bitplan.multimodule/surefire-report.html aggregated result]
 +
 +
= Experimenting with aggregate settings =
 +
<source lang='bash'>
 +
mvn surefire-report:report-only -Daggregate=true
 +
</source>
 +
creates a file surefire-report.html in the directory target/site
 +
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="de" lang="de">
 +
  <head>
 +
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 +
    <title>Surefire Bericht</title>
 +
    <style type="text/css" media="all">
 +
      @import url("./css/maven-base.css");
 +
      @import url("./css/maven-theme.css");
 +
      @import url("./css/site.css");
 +
    </style>
 +
    <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
 +
    <meta name="Date-Revision-yyyymmdd" content="20180825" />
 +
    <meta http-equiv="Content-Language" content="de" />
 +
       
 +
        </head>
 +
  <body class="composite">
 +
    <div id="banner">
 +
                      <div class="clear">
 +
        <hr/>
 +
      </div>
 +
    </div>
 +
    <div id="breadcrumbs">
 +
           
 +
                   
 +
                <div class="xleft">
 +
        <span id="publishDate">Zuletzt veröffentlicht: 2018-08-25</span>
 +
                  &nbsp;| <span id="projectVersion">Version: 0.0.3</span>
 +
                      </div>
 +
            <div class="xright">       
 +
                   
 +
      </div>
 +
      <div class="clear">
 +
        <hr/>
 +
      </div>
 +
    </div>
 +
    <div id="leftColumn">
 +
      <div id="navcolumn">
 +
           
 +
                   
 +
                                      <a href="http://maven.apache.org/" title="Erstellt von Maven" class="poweredBy">
 +
        <img class="poweredBy" alt="Erstellt von Maven" src="./images/logos/maven-feather.png" />
 +
      </a>
 +
                 
 +
                   
 +
            </div>
 +
    </div>
 +
    <div id="bodyColumn">
 +
      <div id="contentBox">
 +
        <script type="text/javascript">
 +
//<![CDATA[
 +
function toggleDisplay(elementId) {
 +
var elm = document.getElementById(elementId + '-error');
 +
if (elm == null) {
 +
  elm = document.getElementById(elementId + '-failure');
 +
}
 +
if (elm && typeof elm.style != "undefined") {
 +
  if (elm.style.display == "none") {
 +
  elm.style.display = "";
 +
  document.getElementById(elementId + '-off').style.display = "none";
 +
  document.getElementById(elementId + '-on').style.display = "inline";
 +
  } else if (elm.style.display == "") {  elm.style.display = "none";
 +
  document.getElementById(elementId + '-off').style.display = "inline";
 +
  document.getElementById(elementId + '-on').style.display = "none";
 +
  }
 +
}
 +
}
 +
//]]>
 +
</script>
 +
<div class="section">
 +
<h2><a name="Surefire_Bericht"></a>Surefire Bericht</h2></div>
 +
<div class="section">
 +
<h2><a name="Zusammenfassung"></a>Zusammenfassung</h2><a name="Summary"></a>
 +
<p>[<a href="#Summary">Zusammenfassung</a>] [<a href="#Package_List">Pakete</a>] [<a href="#Test_Cases">Testf&#xe4;lle</a>]</p><br />
 +
<table border="1" class="bodyTable">
 +
<tr class="a">
 +
<th>Tests</th>
 +
<th>Fehler</th>
 +
<th>Fehlschl&#xe4;ge</th>
 +
<th>Ausgelassen</th>
 +
<th>Erfolgsrate</th>
 +
<th>Zeit</th></tr>
 +
<tr class="b">
 +
<td>2</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>100%</td>
 +
<td>0,002</td></tr></table><br />
 +
<p>Hinweis: Fehlschl&#xe4;ge werden erwartet und durch Behauptungen &#xfc;berpr&#xfc;ft w&#xe4;hrend Fehler unerwartet sind.</p><br /></div>
 +
<div class="section">
 +
<h2><a name="Pakete"></a>Pakete</h2><a name="Package_List"></a>
 +
<p>[<a href="#Summary">Zusammenfassung</a>] [<a href="#Package_List">Pakete</a>] [<a href="#Test_Cases">Testf&#xe4;lle</a>]</p><br />
 +
<table border="1" class="bodyTable">
 +
<tr class="a">
 +
<th>Paket</th>
 +
<th>Tests</th>
 +
<th>Fehler</th>
 +
<th>Fehlschl&#xe4;ge</th>
 +
<th>Ausgelassen</th>
 +
<th>Erfolgsrate</th>
 +
<th>Zeit</th></tr>
 +
<tr class="b">
 +
<td><a href="#com.bitplan.multimodule">com.bitplan.multimodule</a></td>
 +
<td>2</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>100%</td>
 +
<td>0,002</td></tr></table><br />
 +
<p>Hinweis: Die Paketstatistiken werden nicht rekursiv berechnet, es werden lediglich die Ergebnisse aller enthaltenen Tests aufsummiert.</p>
 +
<div class="section">
 +
<h3><a name="com.bitplan.multimodule"></a>com.bitplan.multimodule</h3><a name="com.bitplan.multimodule"></a>
 +
<table border="1" class="bodyTable">
 +
<tr class="a">
 +
<th></th>
 +
<th>Klasse</th>
 +
<th>Tests</th>
 +
<th>Fehler</th>
 +
<th>Fehlschl&#xe4;ge</th>
 +
<th>Ausgelassen</th>
 +
<th>Erfolgsrate</th>
 +
<th>Zeit</th></tr>
 +
<tr class="b">
 +
<td><a href="#com.bitplan.multimodule.TestMain"><img src="images/icon_success_sml.gif" alt="" /></a></td>
 +
<td><a href="#com.bitplan.multimodule.TestMain">TestMain</a></td>
 +
<td>1</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>100%</td>
 +
<td>0,001</td></tr>
 +
<tr class="a">
 +
<td><a href="#com.bitplan.multimodule.TestMain"><img src="images/icon_success_sml.gif" alt="" /></a></td>
 +
<td><a href="#com.bitplan.multimodule.TestMain">TestMain</a></td>
 +
<td>1</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>0</td>
 +
<td>100%</td>
 +
<td>0,001</td></tr></table></div><br /></div>
 +
<div class="section">
 +
<h2><a name="Testflle"></a>Testf&#xe4;lle</h2><a name="Test_Cases"></a>
 +
<p>[<a href="#Summary">Zusammenfassung</a>] [<a href="#Package_List">Pakete</a>] [<a href="#Test_Cases">Testf&#xe4;lle</a>]</p>
 +
<div class="section">
 +
<h3><a name="TestMain"></a>TestMain</h3><a name="com.bitplan.multimodule.TestMain"></a>
 +
<table border="1" class="bodyTable">
 +
<tr class="a">
 +
<td><img src="images/icon_success_sml.gif" alt="" /></td>
 +
<td><a name="TC_com.bitplan.multimodule.TestMain.testMain"></a>testMain</td>
 +
<td>0,001</td></tr></table></div>
 +
<div class="section">
 +
<h3><a name="TestMain"></a>TestMain</h3><a name="com.bitplan.multimodule.TestMain"></a>
 +
<table border="1" class="bodyTable">
 +
<tr class="a">
 +
<td><img src="images/icon_success_sml.gif" alt="" /></td>
 +
<td><a name="TC_com.bitplan.multimodule.TestMain.testMain"></a>testMain</td>
 +
<td>0,001</td></tr></table></div><br /></div>
 +
      </div>
 +
    </div>
 +
    <div class="clear">
 +
      <hr/>
 +
    </div>
 +
    <div id="footer">
 +
      <div class="xright">
 +
              Copyright &#169;                    2018
 +
                        <a href="http://www.bitplan.com">BITPlan GmbH</a>.
 +
            All rights reserved.     
 +
                   
 +
                  </div>
 +
      <div class="clear">
 +
        <hr/>
 +
      </div>
 +
    </div>
 +
  </body>
 +
</html>
 +
 +
= Experimenting with distributionManagement.url settings =
 +
For this we wrote a script to log the results of the mvn site command and analyze where the results go
 +
<source lang='bash'>
 +
#!/bin/bash
 +
# WF 2018-08-24
 +
 +
# prepare to log the mvn site command
 +
sitelog=/tmp/sitelog$$.txt
 +
 +
# create an empty staging area
 +
stage=/tmp/stage
 +
rm -rf $stage
 +
mkdir -p $stage/4site
 +
 +
# run the staging of the site against this directory and log the results
 +
mvn -U clean install site site:stage -DstagingDirectory=$stage/4site | tee $sitelog
 +
 +
# what url did we set for the site in distributionManagement?
 +
cat ../com.bitplan.pom/pom.xml | xml2 | grep  /project/distributionManagement/site/url
 +
# and where did the results go?
 +
egrep "(Pushing|to file)"  $sitelog
 +
 +
</source>
 +
== ${project.baseUri} ==
 +
<source lang='bash'>
 +
/project/distributionManagement/site/url=${project.baseUri}
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module1/com.bitplan.multimodule/multimodule1
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module2/com.bitplan.multimodule/multimodule2
 +
</source>
 +
 +
* the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html {{Done}}
 +
* inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html {{Done}}
 +
== ${project.artifactId} ==
 +
<source lang='bash'>
 +
/project/distributionManagement/site/url=${project.artifactId}
 +
</source>
 +
* failed: Base URI is not absolute: com.bitplan.pom -> [Help 1]
 +
== https://${github.owner}.github.io/${project.artifactId} ==
 +
<source lang='bash'>
 +
/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../multimodule1/com.bitplan.multimodule/multimodule1
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2
 +
</source>
 +
Same result as the working result above ..
 +
* the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html {{Done}}
 +
* inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html {{Done}}
 +
== Test with non -module pom based project ==
 +
<source lang='bash'>
 +
/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
 +
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.fritzbox/target/site
 +
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.fritzbox/com.bitplan.fritzbox
 +
</source>
 +
 +
= Example pom.xml files =
 +
* https://github.com/kohsuke/pom/blob/master/pom.xml (uses wagon-gitsite ...)
 +
* https://github.com/PathwayCommons/cpath2/blob/master/pom.xml
 +
* https://github.com/CoreMedia/joala/commit/5f12395b8b6d84a39c2c11534ec5a509dace4720
 +
* https://gist.github.com/Rocketeer007/f492f8d5e33ecb8b459a8aa6e5e3580e
  
 
= Stackoverflow questions =
 
= Stackoverflow questions =
 +
== site/github pages ==
 
* https://stackoverflow.com/questions/10848715/multi-module-pom-creating-a-site-that-works
 
* https://stackoverflow.com/questions/10848715/multi-module-pom-creating-a-site-that-works
 
* https://stackoverflow.com/questions/21520904/multi-module-example-of-using-mvn-site-deploy-with-github-pages
 
* https://stackoverflow.com/questions/21520904/multi-module-example-of-using-mvn-site-deploy-with-github-pages
 
** https://github.com/trajano/app/blob/wagon-git-example/pom.xml
 
** https://github.com/trajano/app/blob/wagon-git-example/pom.xml
 
** https://github.com/khuxtable/wagon-gitsite (2011)
 
** https://github.com/khuxtable/wagon-gitsite (2011)
 +
** https://mvnrepository.com/artifact/com.github.stephenc.wagon/wagon-gitsite (2014-11)
 +
== aggregating reports ==
 +
* https://stackoverflow.com/questions/1274523/maven-surefire-reporting-plugin-configuration
 +
* https://stackoverflow.com/questions/41766854/maven-multimodule-project-using-surefire-report-plugin-should-generate-aggregate
 +
== conditional parent pom ==
 +
* http://stackoverflow.com/questions/35856843/maven-conditional-parent-pom
 +
** https://github.com/m2spring/wild-inhouse-hybrid-example/tree/property-approach
 +
 +
= Links =
 +
* https://wiki.jenkins.io/display/JENKINS/Site+Creation+and+Deployment
 +
= Documentation =
 +
* https://maven.apache.org/plugins/maven-site-plugin/
 +
* https://maven.apache.org/plugins/maven-site-plugin/attach-descriptor-mojo.html

Latest revision as of 06:49, 9 September 2018

Motivation

The issues

led to the creation of the example project:

in which the github maven site plugin is defined with the configuration 

<!-- git hub site plugin https://github.com/github/maven-plugins -->
<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>${site-maven-plugin.version}</version>
  <configuration>
    <message>Creating site for ${github.owner} ${github.project}
      ${project.version}</message>
    <repositoryName>${github.project}</repositoryName>      <!-- github repo name -->
    <repositoryOwner>${github.owner}</repositoryOwner>    <!-- github username -->
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>site</phase>
    </execution>
  </executions>
</plugin>

Following the suggestion of https://stackoverflow.com/a/19336536/1497139 led to adding 

  <distributionManagement>
    <site>
      <id>${project.artifactId}-site</id>
      <url>${project.baseUri}</url>
    </site>
  </distributionManagement>

to the parent pom.xml 

mvn clean site 
... wait a long while ...

[INFO] Multi-Module ....................................... SUCCESS [04:22 min]
[INFO] Multi-Module 1 ..................................... SUCCESS [04:09 min]
[INFO] Multi-Module 2 ..................................... SUCCESS [04:09 min]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12:42 min

and you end up with Module 2 overriding the results of the Multi-Module and Module 1 results

Is it a bug or a feature?

Whats the work-around?

  1. Do not use the plugin!
  2. git clone or pull the gh-pages to a local folder
  3. mvn site:stage to a temporary staging directory
  4. rsync the results into the git local folder
  5. check in the local folder
  6. have a cup of coffee or drink a beer / be happy ✓

Do not use the plugin!

  1. It's slow (as in really slow ...)
  2. It's not reliable (as in 500 HTML Codes)
  3. It's not maintained well (as in 57 open issues as of 2018-08
  4. It's superflous (see below)
  5. Even the committer's don't use it any more (as in a personal mail I got today ..)

Steps to work around

git clone or pull the gh-pages to a local folder

 git clone https://github.com/$owner/$project --branch gh-pages --single-branch

mvn site:stage to a temporary staging directory

mkdir -p /tmp/stage/4site
mvn -U clean install site site:stage -DstagingDirectory=/tmp/stage/4site
[INFO] --- maven-site-plugin:3.7.1:stage (default-cli) @ multimodule2 ---
[INFO] Using this base directory for staging: /tmp/stage/4site
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO]    >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] Multi-Module ....................................... SUCCESS [  5.423 s]
[INFO] Multi-Module 1 ..................................... SUCCESS [  4.043 s]
[INFO] Multi-Module 2 ..................................... SUCCESS [  3.393 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 13.665 s

Yes - thats right seconds not minutes!

rsync the results into the git local folder

rsync -avz /tmp/stage/com.bitplan.multimodule/* $ghpages/com.bitplan.multimodule

check in the local folder

in the $gphages/com.bitplan.multimodule folder: 

git add *
git commit -m "checking new site in ..."
git push

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

gist of a script

The following bash createSite function does the core work. To call it set the globals ws variable to your workspace and supply the three arguments e.g. 

createSite com.bitplan.multimodule $HOME/Documents/gh-pages "multimodule1 multimodule2"

see the comments of the function below for the description of the three arguments.

createSite bash function

#
# 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
}

Speed comparison

On my computer the plugin takes 18 minutes for the simple com.bitplan.multimodule example

The script needs 25 seconds!

Aggregating Reports

The most highly rated answer of

suggests 

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-report-plugin</artifactId>
      <version>2.4.2</version>
      <configuration>
        <aggregate>true</aggregate>
        <!--also set this to link to generated source reports-->
        <linkXRef>true</linkXRef>
      </configuration>
    </plugin>
  </plugins>
</reporting>

while https://maven.apache.org/plugins/maven-site-plugin/examples/configuring-reports.html suggest that you need different reportsets depending on inherited/non inherited pom configurations

describes details of aggregating. Especially that you have to run the mvn site command twice: 

mvn verify site
mvn site:site site:stage

to get an aggregated result

Experimenting with aggregate settings

mvn surefire-report:report-only -Daggregate=true

creates a file surefire-report.html in the directory target/site Surefire Bericht

Surefire Bericht

Zusammenfassung

[Zusammenfassung] [Pakete] [Testfälle]


Tests Fehler Fehlschläge Ausgelassen Erfolgsrate Zeit
2 0 0 0 100% 0,002

Hinweis: Fehlschläge werden erwartet und durch Behauptungen überprüft während Fehler unerwartet sind.


Pakete

[Zusammenfassung] [Pakete] [Testfälle]


Paket Tests Fehler Fehlschläge Ausgelassen Erfolgsrate Zeit
com.bitplan.multimodule 2 0 0 0 100% 0,002

Hinweis: Die Paketstatistiken werden nicht rekursiv berechnet, es werden lediglich die Ergebnisse aller enthaltenen Tests aufsummiert.

com.bitplan.multimodule

Klasse Tests Fehler Fehlschläge Ausgelassen Erfolgsrate Zeit
TestMain 1 0 0 0 100% 0,001
TestMain 1 0 0 0 100% 0,001

Testfälle

[Zusammenfassung] [Pakete] [Testfälle]

TestMain

testMain 0,001

TestMain

testMain 0,001

Experimenting with distributionManagement.url settings

For this we wrote a script to log the results of the mvn site command and analyze where the results go 

#!/bin/bash
# WF 2018-08-24

# prepare to log the mvn site command
sitelog=/tmp/sitelog$$.txt

# create an empty staging area
stage=/tmp/stage
rm -rf $stage
mkdir -p $stage/4site

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

# what url did we set for the site in distributionManagement?
cat ../com.bitplan.pom/pom.xml | xml2 | grep  /project/distributionManagement/site/url 
# and where did the results go?
egrep "(Pushing|to file)"  $sitelog

${project.baseUri}

/project/distributionManagement/site/url=${project.baseUri}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module2/com.bitplan.multimodule/multimodule2
  • the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html ✓
  • inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html ✓

${project.artifactId}

/project/distributionManagement/site/url=${project.artifactId}
  • failed: Base URI is not absolute: com.bitplan.pom -> [Help 1]

https://${github.owner}.github.io/${project.artifactId}

/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO]    >>> to file:///tmp/stage/4site/../multimodule1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO]    >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2

Same result as the working result above ..

  • the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html ✓
  • inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html ✓

Test with non -module pom based project

/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.fritzbox/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.fritzbox/com.bitplan.fritzbox

Example pom.xml files

Stackoverflow questions

site/github pages

aggregating reports

conditional parent pom

Links

Documentation

Retrieved from "https://wiki.bitplan.com/index.php?title=Multi-Module_Maven_with_github_pages&oldid=7314"