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!
Learn more about Vaadin
Discover the easiest way to build web apps in Java
Related reading that might interest you
Download our free guide to the Future of Web Apps