Add support for Asciidoclet processing of JavaDoc files

[msgilligan]

It would be nice if there were a Gradle DSL for using Asciidoclet. Perhaps it could be bundled in this plugin or be a separate (child or sibling) plugin.

Currently the Gradle configuration for Asciidoclet is somewhat verbose and repeats many lines of boilerplate. It is also typical (or should be typical, especially if configuration were made easier) for projects using Asciidoctor for producing documents to also use Asciidoctor formatting in Java source and vice-versa.

[msgilligan]

I just noticed @mojavelinux had suggested this back in 2014: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/95#issuecomment-52451549

[ysb33r]

I was thinking along the same lines when I saw the asciidoclet issues just some days ago. The solution is to either add an additional plugin on the 2.0 development branch OR, modify the asciidoclet project to also produce a Gradle plugin.

Let's just assume we add an additional plugin here:

• Asciidoclet is not really a doc generator per sé as with the asciidoctor plugin, so it's generation follows a slightly different approach
• A well defined plugin wuld simply add the necessary extensions / method conventions on every Javadoc task that it finds once the plugin is applied.
• There could be a global Gradle extension that sets the version of asciidoclet to use. (Think codenarc, jacoco etc.).
• We need to be careful how we manage the classpath - it will be easier if Javadoc runs out-of-process. For the 2.0 development everything now runs in isolated classpaths, so we have a ot more flexibility on what we can achieve. If Javadoc is going to run in-process on the standard classpaths, we might have some restrictions and might suffer some of the old problems of the 1.5.x series.
• Asciidoctor extensions as mentioned by @mojavelinux could be interesting, but how well it would work could depend on the answer to the previous point.

BTW has Asciidoclet been updated to use the new docket API -> https://bugs.java.com/view_bug.do?bug_id=JDK-8177484

[msgilligan]

Has Asciidoclet been updated to use the new doclet API

Not yet, but we're now in the planning process for this work: https://github.com/asciidoctor/asciidoclet/issues/76

[ysb33r]

Let's explore this concept. We have options for 2.0.