Publishing javadoc to github using maven

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/)

2 Comments

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

  2. bennidi says:

    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… 🙂

Leave a Reply to Javadoc is now available | jTransfo Cancel reply

Your email address will not be published. Required fields are marked *

question razz sad evil exclaim smile redface biggrin surprised eek confused cool lol mad twisted rolleyes wink idea arrow neutral cry mrgreen

*