The title sums up the gist of this idea.
I think making it possible for custom plugins to generate documentation would be a good thing. I also think that if this documentation had the same structure and look & feel as the main gradle documentation it would lead to nice synergies and ease the life of a normal developer using the plugin.
I have applied some of the gradle build logic to my custom enterprise plugin and I now have my plugin project generating dsl reference and docbook user guide documentation. This however took some doing and I still have some issues with the fact that a lot of my classes inherit or otherwise reference the gradle api classes and the DSL reference extraction process does not like the fact that my project does not have the gradle source code checked in to its repository and directly accessible.
As I know gradleware is pushing for some plugin development features in the next few releases, I think adding an easy conventional way for plugins to generate dsl and use guide documentation would be very valuable.