On 25/10/2010, at 12:29 AM, Dierk König wrote: > Hi Paul, > > looks good - and is nicely commented ;-) > > I still think that providing a "blessed" documentation plugin would be > another gradle killer-feature. > > Gradle could leverage some knowledge like: > * building a release needs packaging the docs > * which changes require doc regeneration > * how to link references to the javadoc, groovydoc, etc. > * how to link into the *sources*, e.g. for inlining samples in the docs
I think these are excellent ideas. What I'd like to do at some point, is to introduce a standard lifecycle for documentation projects plus some abstractions for documentation generation and publication. There's a lot in common between documentation and code. The basics are the same: * source files are transformed in various different ways to produce one or more hierarchy of files (documentation markup -> html files, java source -> class files). * the files are bundled up into various archive formats (html files -> zip or epub, classes -> jar or war). * the archives are published to a repository. * the archives are deployed to various environments (html files -> staging or production web server, war -> local or qa or production app server) * source files have transform time dependencies (docbook source -> <xref> elements, java source -> imported classes). These dependencies may need to be resolved from a repository or built locally. * source files have deployment time dependencies (html files -> <a> elements, classes -> imported classes). These dependencies may need to be resolved from a repository or built locally and end up deployed somewhere. I imagine we'd end up with something analogous to a source set for documentation. Each documentation source set would represent some logical documentation component (a user guide, a website, etc). Each documentation source set would produce documentation in one or more formats (html, pdf, etc). By sharing abstractions and conventions between code and documentation, we get a lot of interesting behaviour. As for code, it would be easy to bundle the documentation into archives and publish to a repository. Similarly, as we add deployment for code, we will have the basic pieces for documentation deployment too. And we can blur the distinction between code and documentation. For example, dynamic documentation is really a hybrid between code and documentation. > > (and all that is in addition to making a standard website à la maven) This would simply be another documentation set. It work similar to, say, the 'main' or 'test' source sets that the java plugin adds, where a standard project has by convention a 'developer reports' documentation set. > > I can easily picture some projects going to gradle only because of such a > feature. > > cheers > Dierk > > P.S. one feature that I particularly like about grails-doc is that you can so > easily navigate from the concepts to the details and vice versa. > That's key in understanding anything. I'd really like to add something like that to the Gradle documentation. -- Adam Murdoch Gradle Developer http://www.gradle.org CTO, Gradle Inc. - Gradle Training, Support, Consulting http://www.gradle.biz
