Allow to use an external server for PlantUML #226

Closed ggrossetie closed 3 years ago

The idea is to be able to use an external PlantUML server instead of using java -jar to start a local server.

It could be useful when this library is used in a server environment (for instance GitLab). Currently GitLab is using https://github.com/hsanson/asciidoctor-plantuml but I think it could be nice to merge the two projects.

It might be related to https://github.com/asciidoctor/asciidoctor-diagram/issues/183

I'd even be in support of keeping it as a separate project if it were to become part of this org, as long as it has the support of @pepijnve. My main concern is that we're on the same page and sending a consistent message. As asciidoctor-plantuml clearly fills a need, I think we should find a way to support that need one way or another.

Here's "my plan" 😄

Finish the server_prep branch. The goal of that branch is to split the logic that preprocesses the source code (where applicable), extracts block (macro) attributes, etc and the actual image generation code.
Add support for a diagram-server attribute. If that's set only perform the preprocessing step and generate a plantuml server/kroki.io compatible URL that gets placed in an image block macro.
Kind of a stretch goal this one, add a minimal Sinatra-based frontend for the image generation bit. I.e., take all the diagram processing logic and turn it into a server.

Why is this taking so long? Lack of overlap between spare time and spare energy to do more programming after a day of programming...

Thanks for laying out this plan @pepijnve. It looks good to me. @Mogztter wdyt?

Why is this taking so long?

I would encourage you to never let yourself feel pressured about contributing. Certainly point out when and where you need more help. But if that help isn't there, no one can push you to do more than what feels right for you.

I would encourage you to never let yourself feel pressured about contributing.

No worries Dan, that's not what I was trying to say. It's frustrating to know exactly what you want to do and how to do it, but just not finding the time to make it happen, that's all.

I'm right there with you. I've had a few ideas on my whiteboard fade to almost nothing waiting for me to implement them. It can definitely be frustrating.

Hi, thank you so much for your work! @pepijnve i saw that you finished working on the server_prep branch, did you already include the diagram-server attribute?

@5erv3 yes that got integrated, but it's still very experimental. I did some quick tests and was able to render basic diagrams on kroki.io. The general caveat is that the diagram source code needs to be self-contained. References to external files (e.g., PlantUML includes) are not resolved yet and will not work correctly.

There are two attributes that support this functionality: server-url and server-type. As with other attributes you can specify this at the block level, as a document attribute for a diagram type (use the diagram type prefix, e.g., plantuml-server-url), or as a document attribute for everything (diagram-server-url).

server-type can be either plantuml (the default) or kroki_io.

Feel free to give this a try and log any issues if something isn't working as expected.

Seems not working:

:diagram-server-url: "https://kroki.io/"
:server-type: "kroki_io"

.mermaid
[mermaid]
----
graph TD
  A[ Anyone ] -->|Can help | B( Go to github.com/yuzutech/kroki )
  B --> C{ How to contribute? }
  C --> D[ Reporting bugs ]
  C --> E[ Sharing ideas ]
  C --> F[ Advocating ]
----

Error message:

asciidoctor: ERROR: : line 190: Failed to generate image: undefined method `to_sym' for nil:NilClass Rebuild failed

@edl7878 See https://github.com/asciidoctor/asciidoctor-diagram/blob/master/spec/mermaid_spec.rb#L140 for an example of how to use this functionality.

asciidoctor / asciidoctor-diagram

Allow to use an external server for PlantUML #226