Generating images from embedded text diagrams or AsciiDoc Support in specs2

[phdoerfler]

Specs2's markdown support is great. But sometimes a little diagram would be helpful. While sometimes it is possible to create some ascii art as in
https://etorreborre.github.io/specs2/guide/SPECS2-2.4.17/org.specs2.guide.Design.html#Structure
it can be tedious and there are better alternatives.

In AsciiDoc it is possible to embed diagrams using plain text. These are then converted to images and included in the output. AsciiDoc has a large number of supported formats including plant-uml, mermaidjs and many more. Especially plant-uml is great to generate diagrams showing the architecture of a system.

Of course, it would be possible to have the source of these diagrams in separate files and to run an sbt task which converts them into images prior to running the tests. One could then include them using normal markdown syntax. However, given how modular specs2 is, I can't help but wonder if it would be at all difficult to add this to specs2 directly. Not necessarily full AsciiDoc support (that would be terrific, though), but at least being able to embed, e.g., plant-uml directly in the specs. Maybe as a Fragment:

class DemoSpec extends Specification { def is =
"Embedding Diagrams".title ^
s2"""
This is a little demonstration of embedding diagrams directly in specs2.""" ^
plantUML("""
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
""") ^
s2"""Figure highlighting the interaction between Alice and Bob."""

[etorreborre]

Hi Philipp, this is an excellent idea, I love diagrams too!

The question is how to implement it. I see 3 options:

• Use the fact that pandoc is already a required dependency since pandoc offers some support to Asciidoc.
• Try to use asciidoctorj.
• Embed asciidoctor.js directly in the generated HTML pages to render the diagrams.

I might try to give it a go during the holidays.

[etorreborre]

Hi Philipp, Unfortunately I didn't get the time to even start working on this. And by looking at my schedule (both personal and professional) for 2025 it's unlikely that I'll try anything in the first six months. I'll try to come back to it nonetheless.