check of pom.xml to be compliant with mvn site command for github pages

Question

When trying to publish my open source projects to gh-pages with

mvn site

there have been lots of obstacles recently due to changes in the way maven and github pages works.

After studying

• https://help.github.com/articles/creating-project-pages-using-the-command-line/
• https://maven.apache.org/plugins/maven-site-plugin/
• https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/

Here are some of the needed prerequisites i found and issues i ran into:

prerequisites

1. git branch needs to show a gh-pages branch e.g. after using the commands in https://gist.github.com/ramnathv/2227408
2. the version of the maven-site-plugin and the maven-project-info-reports-plugin have to be correct and correctly configured: maven-site plugins 3.3 java.lang.ClassNotFoundException: org.apache.maven.doxia.siterenderer.DocumentContent
3. dependency.locations.enabled property needs to be false Why am I getting Maven error: "Unable to determine if resource X exists in http://maven.glassfish.org/content/groups/glassfish"?

issues

• How to force GitHub Pages build?
• Maven: Report plugin org.apache.maven.plugins:maven-project-info-reports-plugin has an empty version
• Maven: What is pluginManagement?
• Multi module POM - creating a site that works
• Struggling with Maven parent/child plugin configuration inheritance

not even mentioning work arounds i have to use for ssh-wagon and Java8 javadoc and others

The plugins used are IMHO a "moving target". Something that worked a few months ago in my experience will not work today. So I keep fixing my pom.xml files to keep up and the files grow longer and longer.

See e.g. https://github.com/BITPlan/com.bitplan.simplerest/blob/master/pom.xml

For my internal projects I use a parent pom to make sure that the projects have a common configuration. For the open source projects I did not find a way to use a parent pom for a group of projects yet.

I would like to make sure that a working configuration that i found is "transferred" to other configurations. I am thinking e.g. of

1. a script that might check the configuration
2. some kind of inheritance mechanism like the parent pom

I assume this is a pretty common problem and there are experiences by SO users on how to tackle this issue accross different project.

What would be a good approach and what tools would be useful?

1. parent pom with pom packaging What is "pom" packaging in maven? mostly states the use of pom packaging for multi-module projects but it looks it could be used to have a reference for a parent pom. The parentPath defaults to .. see Maven: Non-resolvable parent POM. The overriding of configurations is explained in Maven : Is it possible to override the configuration of a plugin already defined for a profile in a parent POM

Examples for moving targets

• Java8 silly javadoc settings
  • Maven is not working in Java 8 when Javadoc tags are incomplete
  • How to disable Javadoc warnings in Maven Javadoc Plugin?

Answer 1

As suggested by khmarbaise there is now a common parent pom in place.

mvn site

can be run for all projects using this parent pom with a common set of reports and the result will be transmitted to the corresponding github pages.

A projects specific pom can now be as short as just 25 lines

I am now actually in the process of creating a check script for the pom files and a generate script for the README.md files. This is one of the useful snippets:

usage example:

checkghpages https://github.com/BITPlan com.bitplan.simplerest

Check that the gh-pages exist and create after asking

#
# check the github pages for the given project
# 
# param 1: base url in github
# param 2: project name/directory
#
checkghpages() {
  local l_baseurl="$1"
  local l_project="$2"
  cd $ws/$l_project
  git ls-remote --heads | grep gh-pages > /dev/null
  if [ $? -ne 0 ]
  then
    color_msg $red "github pages branch gh-pages missing for $l_project"
    color_msg $blue "shall i create the branch gh-pages for $l_project?"
    read answer
    case $answer in
      y|Y|yes|Yes|j|Ja) 
        color_msg $blue "creating gh-pages branch for $l_project ..."
        cd /tmp
        # https://gist.github.com/ramnathv/2227408
        git clone $l_baseurl/$l_project
        cd $l_project
        git symbolic-ref HEAD refs/heads/gh-pages
        rm .git/index
        git clean -fdx
        echo "<a href='$l_baseurl/$l_project'>Initial GitHub Page for $l_project</a>" > index.html
        git add .
        git commit -a -m "First pages commit by checkos script"
        git push origin gh-pages
        cd $ws/$l_project
        git pull
      ;;
    esac
  else
    color_msg $green "github pages branch gh-pages for $l_project exists✓"
  fi
}