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

From BITPlan Wiki
Jump to navigation Jump to search
Line 56: Line 56:
 
* [https://github.com/github/maven-plugins/issues/22 Its a bug!]
 
* [https://github.com/github/maven-plugins/issues/22 Its a bug!]
 
=== Whats the  work-around? ===
 
=== 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! ====
 
==== 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 )
 +
==== 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>
 +
====
 
<source lang='bash'>
 
<source lang='bash'>
 
mkdir -p /tmp/stage/4site
 
mkdir -p /tmp/stage/4site
Line 76: Line 90:
 
</source>
 
</source>
 
'''Yes - thats right seconds not minutes!'''
 
'''Yes - thats right seconds not minutes!'''
−
==== get a local stage of gh-pages yourself ====
 
−
<source lang='bash'>
 
−
git clone https://github.com/$owner/$project --branch gh-pages --single-branch
 
−
</source>
 
  
 
= Experimenting with distributionManagement.url settings =
 
= Experimenting with distributionManagement.url settings =

Revision as of 09:28, 24 August 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 )

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

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

==

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!

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

Links

Documentation

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