Styling JavaDoc

For a recent internal project I was asked to publish our APIs online, it was part of a project I was managing; to update our external web site. I had worked hard to style the site according to our brand and I think it turned out quite nice, I must admit. But if you’ve ever worked with javadoc, trying to style it, to make it fit your design you know the frustration I felt when I realized that, well, you don’t style javadoc, javadoc styles you.

Eff that.

With the help of Google (and their Android developer site) I learned how to bend the matrix to my needs. The secret is a project called doclava. From the project’s Google Code site:

Doclava (rhymes with baklava) is a custom Javadoc doclet used to generate documentation. Key differences between Doclava and the standard doclet include:

Refreshed look and feel, including search capabilities.Embeds versioning information in the documentation.Uses a templating engine for user customizations.Throw build errors for things that can easily be caught, like @param tags that don’t match the parameter names.Ability to include snippets of code from real source codeFederate documentation between multiple sites.Ability to embed javadocs in a larger web page.

Doclava uses JSilver as its templating engine, a pure-Java implementation of Clearsilver.

Very cool. Thank you Google.

How to do it

Download doclava, unzip and create a directory structure like this:

MyJavaDocProject
 |- doclava-1.0.6
     |- doclava-1.0.6-javadoc.jar
     |- doclava-1.0.6-sources.jar
     |- doclava-1.0.6.jar
 |- generated-docs
 |- templates
     |- class.cs
     |- classes.cs
     |- components.cs
     |- . . .

The generated-docs folder should be an empty folder. This is where your resulting javadoc will be created. Thetemplates folder should be a copy of res/assets/templates as found in the source code.

Alright. To make it all happen we execute javadoc with the doclava docket like this:

javadoc -XDignore.symbol.file=true -encoding "ISO-8859-1" -quiet -doclet com.google.doclava.Doclava -docletpath ./doclava-1.0.6/doclava-1.0.6.jar -d ./generated-docs/ -sourcepath /path/to/my/java/project/src/ -subpackages @include_packages.txt -exclude @exclude_packages.txt -templatedir ./templates/

Some stuff in there is specific to my use case (ignore.symbol.file and encoding, for example) and you can leave out the include and exclude packages lists if you like but it makes it easy for me to filter stuff we don’t want to publish.

You might wanna check out the documentation for javadoc.

And now all you have to do is to hack away in the templates folder, dropping in any assets you might have (we useTwitter Bootstrap with everything that comes with it). It’s all pretty much HTML from here. You can do fancy stuff with the JSilver tempting engine but you most likely do not have to, most stuff is already taken care of.

Frameless

Perhaps the best thing about the doclava project is that it displays the javadoc without frames. Frames break the web, in my opinion, so this was really appreciated.

Again, thank you very much Google.

(Originally published 2013–04–03)