Multi-Module Maven with github pages
Motivation
The issues
led to the creation of the example project:
- https://github.com/BITPlan/com.bitplan.multimodule which uses
- https://github.com/BITPlan/com.bitplan.pom for the parent pom definition
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?
Do not use the plugin!
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!
get a local stage of gh-pages yourself
git clone https://github.com/$owner/$project --branch gh-pages --single-branch
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 | 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/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO] >>> to file:///tmp/stage/../multimodule1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO] >>> to file:///tmp/stage/../multimodule2/com.bitplan.multimodule/multimodule2
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
Stackoverflow questions
- 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