We do plan to turn the user guide and DSL reference generation stuff into a real plugin that you can use to publish documentation about your custom plugins and other build infrastructure. So, this might solve your problem.
I would imagine that such a plugin would eventually end up supporting various different documentation formats. It would allow docs to be written in docbook, but might also allow you to mix in, say, docs written in markdown.
As far as docbook itself goes, there are some advantages and disadvantages. From an authoring point of view, some advantages: * The model is very rich, which can be useful at times for creating precise docs, and allowing the tooling to do interesting things. * It’s possible to aggregate a larger document from smaller pieces. * The tooling runs on the jvm, and is available in various repos, so that you can just clone the gradle repository and start working on the docs, without needing to install anything.
Some disadvantages: * It’s a pain to write documentation in XML. * The tooling is very slow.
From an automation point of view, there are some big advantages, as the documentation ends up as XML with a rich model, so it is easy to chain a bunch of transformations, to mix in some generated the content, and so on.
In other words: For the author, docbook is a pain. For the tooling, docbook is good.
What I’d like to do with our documentation system is to come up with a way to allow user guide chapters and DSL reference material to be written in either markdown (or similar) or docbook - whichever is appropriate for that content - and have the tooling merge this content into a single docbook document that travels down the tool chain.