Close
Back

Host your JavaDoc’s online in GitHub

It’s Thursday evening and you have just finished your new awesome Vaadin Add-on. The very last commit is pushed to github, the .zip is uploaded to the directory, the release notes are updated, you lean back and take a five? Ok, you are great, but wait... Where is your add-on’s javadoc? Of course, javadoc .jar is included in the addon archive by default, and modern IDEs use that, but let’s show your perfect API to the developers, who still haven’t included your addon to their projects.

Fortunately, I know how to publish your javadoc in just one minute with the help of https://pages.github.com/.

They are, in fact, simple static pages hosted at http://<yourname>.github.io/<yourproject> and it looks like a good place for the API documentation.

Step-by-step instructions

When you build a release of your Java library with Maven, Maven automatically generates the javadocs in the target/apidocs folder of your project.

Go to the javadoc directory

cd target/apidocs

Create a new temporary repository

git init

Add github as a remote repository. I prefer to use a non-standard name for remote, just to not push the documentation to the wrong place.

git remote add javadoc https://<your name>@github.com/<your name>/<your project>.git

It’s better to keep the history of the documentation branch, so do not use “push --force”. Instead of that, fetch the very last commit of the github-pages branch.

git fetch --depth=1 javadoc gh-pages

The following commands perform a special merge and add all of your newly created documentation as a new commit to the existing branch.

git add --all
git commit -m ""
git merge --no-edit -s ours remotes/javadoc/gh-pages

After that, the master branch of the temporary repository contains 3 commits - one old (your previous documentation version), one new and the merge. Let's push them to a remote gh-page.

git push javadoc master:gh-pages

Optionally, you may delete all git-related files.

rm -r -f .git

That's all! Visit http://<yourname>.github.io/<yourproject> and check it out. And do not forget to add the link to your Vaadin directory page!

Comments
Add Comment
fatal: 'remotes/javadoc/gh-pages' does not point to a commit
Posted on 7/7/16 3:42 PM.