Asciidoctor extension support

[johncarl81]

Asciidoctor supports extensions. It would be fantastic to be able to leverage extensions in asciidoclet.

Concretely, I'm thinking about the https://github.com/asciidoctor/asciidoctor-diagram extension. Supporting this extension would allow us to generate uml in javadoc code, like the following:

http://asciidoctor.org/news/2014/02/18/plain-text-diagrams-in-asciidoctor/

This would be yet another game changer.

[mojavelinux]

We've learned in the Maven and Gradle plugins that extensions written in Java (or Groovy) will self register if they are on the classpath. As long as the plugin configuration allows additional classpath entries, you are set there. For an example that proves it works, see this Gradle project: https://github.com/aalmiray/asciidoctor-gradle-example

In order to allow extensions written in Ruby to work, you need to allow the gemPath to be specified. I've added this feature in both the Gradle and Maven plugin. You can see the change in this pull request: https://github.com/asciidoctor/asciidoctor-maven-plugin/pull/110/files#diff-bff21eb5b34bf9d1e453446858f86203R167

It's still up to the user to stage the gems in an exploded directory and passing that location to the gemPath property. I explain the situation clearer in the issue for the Maven plugin: https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/109

While we're at it, we should also add the Ruby environment isolation that we've added to both the Maven and Gradle plugin. This is as simple as passing null to the create() method (with a special try/catch until AsciidoctorJ 1.5.1). It's also accomplished by telling the user to select rvm use system before running the build.

Though it sounds complex, it's really just a small change around how we instantiate AsciidoctorJ.

[mojavelinux]

I agree, it will be a big game changer.

For Asciidoctor Diagram, there's the small issue that it generates the images in the same directory (or child directory of) the source. We're working on getting this fixed, though the configuration in Asciidoctor Diagram will provide a key use case to study for getting it right.

[benevans]

Would it be worth repackaging the asciidoctor-diagram gem as a jar so it can be easily resolved by Maven/Gradle/etc? That way asciidoclet users don't have to install the gem.

It could even load automatically by using asciidoctorj's ExtensionRegistry:

public class AsciidoctorDiagramExtension implements ExtensionRegistry {
    @Override
    public void register(Asciidoctor asciidoctor) {
        asciidoctor.rubyExtensionRegistry().requireLibrary("asciidoctor-diagram");
    }
}

[mojavelinux]

This is part of a broader discussion I plan to initiate on the list. I think the gem proxy repository for Java is missing the main point for redistributing gems because they aren't loadable by default. We can definitely use bintray to solve this issue. I want to make sure we solve it the right way.

[johncarl81]

This looks fantastic.

I immediately came across the bug that generates the images in the source root directory (in this case the home directory of the project).

Also, after asciidoctor/asciidoctor-diagram/issues/39 will the image render in the proper destination? For instance, if we add a [graphviz, dot-example, svg], to the org.asciidoctor.Asciidoctor class, the rendered <img/> tag will point to a relative .svg file. This means the .svg will need to be in the ${project.basedir}/target/apidocs/org/asciidoctor/ directory (on Maven at least).

Another qualm: it requires quite a few parameters, ie:

<additionalparam>
    --gem-path /var/lib/gems/1.9.1
    -r asciidoctor-diagram
    -d ${project.basedir}/target/apidocs
</additionalparam>

Is there any way to provide a default destination directory?

[mojavelinux]

On Wed, Aug 20, 2014 at 8:59 PM, John Ericksen notifications@github.com wrote:

Is there any way to provide a default destination directory?

That's what we'll work on accomplishing in the next version (or some future version) of Asciidoctor Diagram.

We are hitting this challenge because Asciidoctor now extends beyond what AsciiDoc Python could ever do...so we have to stop to think and design a solution :)

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen

[johncarl81]

@mojavelinux, in your opinion will this related PR leave the door open for this fix? Is there anything else we can do in this release?

[mojavelinux]

Not much we can do here. You'll inherit this fix once we solve the problem in Asciidoctor Diagram. Asciidoclet is doing everything right.

Btw, in order to get the diagrams to work in the Javadoc output, just set the data-uri attribute. That's probably best anyway since it keeps the HTML self contained. Asciidoctor Diagram will still leave behind image files in the project root, but you can use a cleanup script to nuke them in the interim.

[johncarl81]

Good deal.. will merge in shortly.

[mojavelinux]

Here's the broader discussion I was mentioning that will (hopefully) reduce the configuration complexity. We have a distribution problem, atm, which is putting the burden on the user to fix with extra plugins and configuration.

http://discuss.asciidoctor.org/RubyGems-proxy-for-JRuby-missing-major-use-case-td2075.html