Publishing javadoc to github using maven

Posted on September 9, 2013 by justme

GitHub has the ability to publish static site documentation using GitHub pages.

This can be used in your project to publish for example the javadoc.

For starters, you need to create a gh-pages branch in your project (example here is for my user (joachimvda) and the jtransfo project).

git clone git@github.com:joachimvda/jtransfo.git
cd jtransfo
git checkout --orphan gh-pages
git rm -rf .
cat "placeholder" >index.html
git add index.html
git commit -am "initial pages commit"
git push origin gh-pages

Now add a section to your pom to generate the javadoc and publish to the gh-pages branch. In this case, I aggregate the javadoc for all modules. Add the following to the build/plugins section:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9.1</version>
    <configuration>
        <aggregate>true</aggregate>
        <show>public</show>
        <nohelp>true</nohelp>
        <header>jTransfo, ${project.version}</header>
        <footer>jTransfo, ${project.version}</footer>
        <doctitle>jTransfo, ${project.version}</doctitle>
        <links>
            <link>http://static.springsource.org/spring/docs/3.0.x/javadoc-api/</link>
        </links>
    </configuration>
</plugin>
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-scm-publish-plugin</artifactId>
    <version>1.0-beta-2</version>
    <configuration>
        <checkoutDirectory>${project.build.directory}/scmpublish</checkoutDirectory>
        <checkinComment>Publishing javadoc for ${project.artifactId}:${project.version}</checkinComment>
        <content>${project.reporting.outputDirectory}/apidocs</content>
        <skipDeletedFiles>true</skipDeletedFiles>
        <pubScmUrl>scm:git:git@github.com:joachimvda/jtransfo.git</pubScmUrl>
        <scmBranch>gh-pages</scmBranch> <!-- branch with static site -->
    </configuration>
</plugin>

You can now build and publish the javadoc by using the following maven command:

mvn clean javadoc:javadoc scm-publish:publish-scm

The pages are now accessible at http://joachimvda.github.io/jtransfo/.

Add a nice link from your README.md

[javadoc](http://joachimvda.github.io/jtransfo/)

Javadoc is now available | jTransfo says:

September 9, 2013 at 23:28

[…] For details on how this was done, see here. […]

bennidi says:

January 10, 2014 at 15:41

Concise explanation. THank you so much, it worked exactly as described. Small improvement for the tutorial: Before running the maven command you have to switch back to the master branch (obvious but for the sake of completeness… 🙂