Using kroki.io to support additional diagram types.

wfouche commented 5 years ago

The latest release of the asciidoc plug-in for the Chrome browser supports a wide range of diagram types via kroki.io:

The upside to how this functionality is implemented, is that no client side installs of diagram tools are required. No graphviz, or other installs are needed.

At the moment if I create a mermaid diagram in IntelliJ/Asciidoc

[mermaid,mermaid.png]
----
sequenceDiagram
    participant Alice
    participant Bob
    Alice->John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!
----

if is of course not displayed by IntelliJ/Asciidoc

Failed to generate image: Could not find the 'mermaid' executable in PATH; add it to the PATH or specify its location using the 'mermaid' document attribute
sequenceDiagram
    participant Alice
    participant Bob
    Alice->John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!

but if I click on the browser ribbon in IntelliJ/Asciidoc and select Chrome, then the mermaid diagram is displayed in the browser (via kroki.io)

Could similar support for the diagram types supported by kroki.io be added to the asciidoctor-intellij-plugin?

ahus1 commented 5 years ago

kroki.io is a cloud service (currently free). It relies on the fact that the diagram contents are sent to a remote server. I know customers who use it for internal documentation, and I know they don't want their diagram contents to be sent over to the internet.

I think this is problematic at best for a editor like IntelliJ, and don't think there is a way to support this in a secure way. It might be better suited for published online documentation that is freely available.

What is already supported in the plugin today:

For some diagram types like mermaid a local executable is required. Once this is installed, you specify an attribute pointing to the executable (either in the asciidoc file itself, in an .asciidoctorconfig, or in the plugin's configuration). I haven't used mermaid before;

If you think kroki.io works for you in your working environment, one thing you can do today:

the .asciidoctor-folder allows you to install project-local ruby extensions for asciidoctor. The asciidoctor-kroki-extension is written in JavaScript. It would need to be re-written in Ruby to make it work with the JRuby version of Asciidoctor. See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-for-Asciidoctor-Extensions for details. Every time you open the project you'll need to confirm that you want to execute the extension.

wfouche commented 5 years ago

I agree that sending diagram specifications out across the internet to be rendered as an image, would be problematic for many companies and individuals. Fortunately, I see Kroki's source code is on Github and Docker images are built from the source code that anybody can host on a local corporate network. See https://github.com/yuzutech/kroki for more details.

The upside of supporting Kroki in some or other way, is the ease of installation. Just install the Asciidoc plug-in inside IntelliJ, apply a few additional configuration steps, and viola! You can diagram away to your heart's content. Currently rolling our the Asciidoc plug-in to developers and technical writers will require a lot of additional work if diagram types other than plantuml and graphviz are required.These extra tools also need to be updated and one have to ensure that everyone has the same versions of the various diagram tools.

Thanks for the feedback with the information provided in (1) and (2). I'll investigate this further, and plan to share the results of further testing.

ahus1 commented 5 years ago

Thanks for sharing more information about the environment you plan to use it in.

Once there is a ruby extension as part of option (2), this could at some point be bundled with the IntelliJ plugin as long as it addresses the privacy/confidentiality issues. This would include a disabled-by-default configuration, an option to specify an URL for a kroki instance either per installation or per project and a UX that informs the user about what she/he is giving consent to.

ggrossetie commented 4 years ago

Once there is a ruby extension as part of option (2), this could at some point be bundled with the IntelliJ plugin as long as it addresses the privacy/confidentiality issues.

I can work on that. Any special requirements I should be aware of?

This would include a disabled-by-default configuration, an option to specify an URL for a kroki instance either per installation or per project and a UX that informs the user about what she/he is giving consent to.

Does the plugin already have a configuration page?

ahus1 commented 4 years ago

Thank you very much for volunteering!

There is a working ruby extension in the plugin for the operation macro of spring-rest-docs, see here: https://github.com/asciidoctor/asciidoctor-intellij-plugin/blob/master/src/main/resources/springrestdoc-operation-blockmacro.rb. The recipe would be:

place your file in the same folder
ensure that the .rb file also registers the extension (at end of file)
when you log errors or warnings, use message_with_context to log also the line number of the current file. This way the logs will show as warnings and errors in the editor at the appropriate line

Once the extension is ready, you register it in AsciiDoc.java. This class caches Asciidoctor instances with different configurations. It creates a hash for each configuration depending on the extensions loaded to distinguish them.

To make it configurable you can as a first step use the attributes in the plugin's configuration. There is some code in Asciidoc.java already that accesses getAsciiDocPreviewSettings().getAttributes() This way you don't need to change the UI of the configuration.

I found creating UIs in IntelliJ quite tedious for quite some time, but know I found my way around. I'd be happy to contribute the configuration part. Or I walk you through it once we are there.

Godspeed!

ggrossetie commented 4 years ago

I'm making some progress on this issue:

kroki-ext

I don't know why but SVG are not rendered properly in the preview but png images are fine.

To make it configurable you can as a first step use the attributes in the plugin's configuration. There is some code in Asciidoc.java already that accesses getAsciiDocPreviewSettings().getAttributes() This way you don't need to change the UI of the configuration.

Where do I configure the settings?

ggrossetie commented 4 years ago

Never mind, I just found the following comment in plantuml-png-patch.rb :laughing:

The JavaFX preview doesn't support SVG well. Therefore we'll render all PlantUML images as PNG

ahus1 commented 4 years ago

A new pre-release 0.30.10 of this plugin includes this feature. The preview is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

asciidoctor / asciidoctor-intellij-plugin

Using kroki.io to support additional diagram types. #287