Maven site
is a great tool as well as GitHub. The coolest thing about those tools is that
they play together very well. Only a little Maven configuration is needed. But let
me explain shortly what both tools do.
Maven Site: generates automatically a nice documentation website for your Maven project. Many Apache projects uses this generated site as their main website. So probably you have already seen such generated websites. An nice example is the my (parent) POM project or the maven-site-plugin. Mainly the documentation consists of three parts:
Maven Site: generates automatically a nice documentation website for your Maven project. Many Apache projects uses this generated site as their main website. So probably you have already seen such generated websites. An nice example is the my (parent) POM project or the maven-site-plugin. Mainly the documentation consists of three parts:
- Project information like dependencies, license, source repository and so on.
- Project reports like unit tests reports, static code analysis reports, JavaDocs and so on.
- The documentation written by the developers. With an additional Maven Plugin it's possible to write the documentation with Markdown.
Before you start with the Maven configuration you should read Creating Project Pages manually for a better understanding.
Before we can start with the GitHub Pages integration into Maven we firstly need to correctly build the website. For multi module projects it's necessary to deploy (locally is sufficient) the website first. Otherwise the references between modules won't work. To do so you just need to configure the distribution management like this:
<distributionManagement>
<site>
<id>site-docs</id>
<url>file://${env.HOME}/sitedocs/pom-project</url>
</site>
</distributionManagement>
<site>
<id>site-docs</id>
<url>file://${env.HOME}/sitedocs/pom-project</url>
</site>
</distributionManagement>
How to
fully configure the generation of the Maven Site is too much for this blog
post. Look at the POM for
some good basic configuration or just us it as parent POM for your project. The
minimum of configuration is:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.4</version>
<executions>
<!-- used for multiproject builds -->
<execution>
<id>attach-descriptor</id>
<goals>
<goal>attach-descriptor</goal>
</goals>
</execution>
</executions>
<dependencies>
<!-- To use the Markdown format -->
<dependency>
<groupId>org.apache.maven.doxia</groupId>
<artifactId>doxia-module-markdown</artifactId>
<version>1.6</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.7</version>
<configuration>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
<reportSets>
<reportSet>
<reports>
<report>index</report>
<!--<report>cim</report>-->
<report>dependencies</report>
<!--<report>dependency-convergence</report>-->
<report>dependency-info</report>
<report>dependency-management</report>
<!--<report>distribution-management</report>-->
<!--<report>issue-tracking</report>-->
<report>license</report>
<!--<report>mailing-list</report>-->
<report>modules</report>
<report>plugin-management</report>
<report>project-team</report>
<report>scm</report>
<report>summary</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.4</version>
<executions>
<!-- used for multiproject builds -->
<execution>
<id>attach-descriptor</id>
<goals>
<goal>attach-descriptor</goal>
</goals>
</execution>
</executions>
<dependencies>
<!-- To use the Markdown format -->
<dependency>
<groupId>org.apache.maven.doxia</groupId>
<artifactId>doxia-module-markdown</artifactId>
<version>1.6</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.7</version>
<configuration>
<dependencyLocationsEnabled>false</dependencyLocationsEnabled>
</configuration>
<reportSets>
<reportSet>
<reports>
<report>index</report>
<!--<report>cim</report>-->
<report>dependencies</report>
<!--<report>dependency-convergence</report>-->
<report>dependency-info</report>
<report>dependency-management</report>
<!--<report>distribution-management</report>-->
<!--<report>issue-tracking</report>-->
<report>license</report>
<!--<report>mailing-list</report>-->
<report>modules</report>
<report>plugin-management</report>
<report>project-team</report>
<report>scm</report>
<report>summary</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
To build
the Maven Site just use: mvn clean site site:deploy
The
integration into the GitHub pages is very easy and looks like this:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-publish-plugin</artifactId>
<version>1.1</version>
<inherited>true</inherited>
<configuration>
<checkoutDirectory>${project.basedir}/github.com</checkoutDirectory>
<checkinComment>publishing site documentation</checkinComment>
<content>${env.HOME}/sitedocs/pom-project</content>
<pubScmUrl>scm:git:https://github.com/rseiler/pom-project.git</pubScmUrl>
<scmBranch>gh-pages</scmBranch>
</configuration>
</plugin>
</plugins>
</build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-publish-plugin</artifactId>
<version>1.1</version>
<inherited>true</inherited>
<configuration>
<checkoutDirectory>${project.basedir}/github.com</checkoutDirectory>
<checkinComment>publishing site documentation</checkinComment>
<content>${env.HOME}/sitedocs/pom-project</content>
<pubScmUrl>scm:git:https://github.com/rseiler/pom-project.git</pubScmUrl>
<scmBranch>gh-pages</scmBranch>
</configuration>
</plugin>
</plugins>
</build>
Additional
you need to configure your username and password in the .m2/settings.xml. It
should look like this:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
<server>
<id>github.com</id>
<username>github-username</username>
<password>github-password</password>
</server>
</servers>
</settings>
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
<server>
<id>github.com</id>
<username>github-username</username>
<password>github-password</password>
</server>
</servers>
</settings>
If
everything is done just type:
mvn clean site site:deploy
scm-publish:publish-scm -Dscmpublish.dryRun=true
The scmpublish.dryRun
flag prevents the plugin to commit anything and just outputs what changes it
would commit. Check it and if everything works than rerun the command without
this flag:
mvn clean site site:deploy scm-publish:publish-scm
That's it! It's
Very simple :)