#104 Support for creating diagrams from text (eg. Graphviz, diagrams.js, PlantUML, etc.)
Opened 12 days ago by blaise. Modified 5 days ago

TL;DR:

Diagrams of components, sequences, and workflows are hard to update, paragraphs are easy. Doc authors would benefit from the ability to describe flows in plain text and compile to graphics.

Plugins for compiling text into graphics

In readthedocs.org, (Sphinx) this feature is available using https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html.

Graphviz is based on Java and widely available as a library for processing diagrams written in simple markups (with names like dot and neato).
The markup conventions have been adopted and extended by projects on other platforms such as viz.js and diagrams.js

So it becomes a matter of:

  1. authors describing processes in text, and
  2. servers compiling into diagrams, using their favorite family of dependencies (eg. Graphviz/Java, viz.js/Node, etc)

Preview plugins for popular IDEs:

Graphviz references

Alternatives

  • Vis.js: Perhaps the most powerful of the NodeJS-based options, it supports multiple input languages.
  • Mermaid.js
  • Diagrams.js powers some other projects and IDE plugins.
  • Viz.js Org Not the same as Vis.js

Super cool, taking it to the next level...


I think it's a awesome idea, Asciidoctor has this implemented (w/ 'asciidoctor-diagram' gem) and Antora doesn't.

Right now maybe we could just write it as a simple script that creates the diagrams with graphviz and then puts them in _images directory.

Can you submit this as the issue to Antora? https://gitlab.com/antora/antora/issues

I'm sure we are not the only ones who think that graphviz support is very valuable for the documentation.

We should put the information and how to run graphviz into
https://pagure.io/fedora-docs/documentation-contributors-guide

Actually there would be great if there was a better concensus amongst contributors on what kind of standards we are implementing in the docs, also we need more people on contributors guide.

thank you for bringing this up!

Done> https://gitlab.com/antora/antora/issues/353

OK, re: contributors,
I think there are two user stories:

As a contributor,

I expect to be able to describe a diagram using text arranged in {$LANG} syntax. Then I designate that block of text to be rendered as a diagram using {$DIRECTIVE} in a file of {$MARKUP} content
.. code::pseudo

  • {$LANG} = ['dot', 'neato', 'network', 'seqdiag']
  • {$DIRECTIVE} = {'rst' : '.. graphviz::', 'adoc' : '.graphviz'}
  • {$MARKUP} = ['rST', 'adoc', 'md']

As a sysadmin

I expect to be able to install a server module that will recognize special directives in a file and pass the content to a renderer, then receive a graphic object and insert the object into the output.

@ojn : Excellent suggestion!

Can you submit this as the issue to Antora? https://gitlab.com/antora/antora/issues
I'm sure we are not the only ones who think that graphviz support is very valuable for the documentation.
We should put the information and how to run graphviz into
https://pagure.io/fedora-docs/documentation-contributors-guide

I opened https://gitlab.com/antora/antora/issues/353#note_121526339
and immediately got this back from Dan at Antora:

If we wanted to run our own PlantUML instance:
https://github.com/eshepelyuk/asciidoctor-plantuml.js#plantuml-server
is that a request to the infrastructure team?

Do @bex or @asamalik , @ojn know if we have a playbook repo available?
Apparently, I need to refer to the plantuml module in the Antora playbook for this project.

TIL from @asamalik that we have a playbook in:
https://pagure.io/fedora-docs/docs-fp-o/blob/master/f/site.yml
but it's not clear to me how to extend it to include:

I opened https://gitlab.com/antora/antora/issues/353#note_121526339
and immediately got this back from Dan at Antora:
https://github.com/eshepelyuk/asciidoctor-plantuml.js#antora-integration

nor can I figure out how to get anyone to help.

Login to comment on this ticket.

Metadata