Macro-based diagram syntax does not work in Documenter.jl for any diagram type except PlantUML
albinahlback opened this issue · comments
Is there an example of mermaid I could use? I only get plantuml to work.
Hi @albinahlback thanks for giving this a shot! I'm sorry for not getting back to you sooner, but my GitHub notifications tend to get out of hand at which point GitHub stops e-mailing me, so I only just noticed...
I've been meaning to get back to this package and adding some examples, but unfortunately, other priorities have gotten in the way. Happy to help out though! Can you elaborate a bit on what's not working for you?
(Parts of) PlantUML are the only diagrams that can be rendered to text at the moment (this is a restriction in the underlying libraries, not something this package can take care of). In all other cases, the textual description of the diagram is rendered instead. However, when the descriptions are created in a rich-media environment all supported diagram types should work "as-is". For instance, rendering the Mermaid example from Kroki's documentation in Pluto results in
Hope this helps, but do let me know if you need further clarification.
Yes, so I would like to use this in the documentation for a package I want to develop. In a markdown file I have then tried to write something like
```@setup diagram
using Kroki
mermaid_diagram = mermaid"""
graph LR
A --> B
"""
```
```@example diagram
mermaid_diagram #hide
```
which does not work.
That sounds like the perfect use-case, and that should definitely work. But, I've verified it to currently indeed not work... From some quick samples I have tested, it looks like this actually affects all diagram types, except for PlantUML.
Given that the macro-syntax does work when used in the context of Pluto and that PlantUML also seems to work, there must be something at odds here in the context of Markdown and/or Documenter.jl for these diagram types. I'll have to look a bit deeper into that.
That being said, you can still get this to work by using the (slightly) long(er) form syntax like this:
```@setup LongformMermaidDiagram
using Kroki
mermaid_diagram = Kroki.Diagram(:mermaid, """
graph LR
A --> B
""")
```
```@example LongformMermaidDiagram
mermaid_diagram #hide
```
I hope that's not too off-putting, but I certainly agree it's not ideal. I have actually been working on making the syntax
```mermaid
graph LR
A --> B
```
work as well in the context of Documenter.jl, so there may be some light on the (distant) horizon. I'm not happy with the current implementation of that though, so I haven't shipped it yet.
I'll repurpose this issue to target the more general issue at hand, so I have a reminder to take a look at it.
Perfect, I will use this then. Thank you very much!
By the way, really good job and a big thank you for creating this package. I think more of the community should use this instead of rendering images.
Thank you for the kind words! I've been using these types of tooling more and more over the past couple of years and am missing them every time they're not readily available. Hence the existence of this package 😄 I think it's mostly a lack of knowledge of the existence of these types of tools, the value of visualization in the context of software documentation, and how easy those visualizations are to do with tooling like this. I'd like to try and change that a bit 😄
Unfortunately, I haven't been able to use it in the context of my Julia work recently, but I'm looking forward to getting back into that. Feedback like this certainly helps!
I've tried to reproduce this issue again, but can no longer seem to do so. I've tried various Julia versions from v1.4 through to v1.7, but on all of them the string literal syntax works as expected. This can also be seen in the newly added examples section through #11.
This leaves the possibility that it was either an issue with the version of Documenter.jl (but I didn't update the version prior to running the tests) or that something was off with the Kroki service at the time. Either case is a bit difficult to verify, so I'm going to close this as the behavior works as intended again.
I'm sorry for taking this long to address this.