Groovydoc and Maven
One of the things we discovered this last week, when trying to release to Apache Maven Central, was that javadoc (which is required for every artifact that has code in it) was not being generated for our Groovy artifacts.
Now in the past, we have used GMaven, which generated stubs (albeit poorly) and those caused the javadoc to trigger off, but since we moved to the Eclipse Maven plugin, this no longer worked - it compiling them both together. So we needed to start using actual Groovydoc - and it turned out, on a brief search, that there was no Maven plugin for Groovydoc.
There was however an Ant plugin, but having an Ant script, although nice that it can be dropped back to, is usually somewhat error prone and can lead to difficult configuration problems. That seemed to be the case for the Ant plugin as well, with quite a few people not being able to get it working. One of the good things however that I discovered was that the real work was in fact done outside of the Ant Groovydoc task - it just collected the information and passed it on.
The one thing I learned however, and the reason I am writing this up, is that source paths must be relative. If you pass a path that ends up having the full path to the file in it, Groovydoc will treat it as being in the Default package - and you will get a whole lot of classes in your DefaultPackage in the generated documentation. If you encounter this problem when using Ant or Gradle, then this will be the reason - make sure you use offsets from the directory where you run the build script from.
I have sorted this problem out in the Maven build, and it will pick up all source directories that get added and include them - this means generated sources and anything you add with the build helper Maven plugin.
The documentation and source is over on Github, and the artifact is in Maven Central.
No comments:
Post a Comment