Sunday, March 29, 2015

Automatically syncing up your project reports, javadoc and groovydoc, README.md markdown, and github page with gradle and travis-ci.

I've been working on trying to start a *very* simple open source library, but quickly found that I don't want to spend a bunch of time keeping all my docs and websites for it in sync. I'd much rather make a quick README.md file that describes everything, and let my build system do the rest.

While exploring this, the first thing I came across was looking for a gradle site plugin, and I found a good one at https://bitbucket.org/davidmc24/gradle-site-plugin

Integrating this is simple, and you can place all your web files in your src folder under "site" per standard maven site convention.  But I also wanted to add all my gradle reports, and my doclet outputs as well. Not to mention my README.md file which documents all the usage of the api. Here is a gist of how I found best to do it:

At this point I was able to make my page template, and also be able to link to any of my doclet pages (and reports if I choose). Next, I needed a simple way to import the README.md into my html template, so I don't have to duplicate all my usage/intro docs. I found some options like http://strapdownjs.com/, however it pretty much will take over your page with it's embedded bootstrap configuration. It also required placing your markdown div directly in your body, and not embedded where you want. I instead opted that doing this manually wouldn't be hard by using the marked library with highlight.js. And came up with the following gist that replaces any element (in my case an empty div) with an id of README:

But I still didn't want to have to copy my site output manually and commit to the gh-pages repo. If I just commit my changes, it should just automatically publish right? To bridge the gap between the maven site publishing and github pages, I leveraged a bash script in my travis-ci build. Below is the script I wrote. Note, I'm dumping all output from the actual git push to /dev/null to protect exposing the github api key in case of an error.

The last step then is to put in a hook into your .travis.yml file. For context I'm showing my entire travis file, your build will change obviously. The important part is the call to the gradle buildSite task provided by the gradle plugin, the call to the bash script, and the environment variables. It's also very important to embed your github api key into a secure parameter, this is checked in publicly you know ;-)

For an example, check out my project page at http://aweigold.github.io/lemming/ and my source at https://github.com/aweigold/lemming.