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.
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
dot
neato
So it becomes a matter of:
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:
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
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.
Actually I'm not sure that integrating the PlantUML server is a good idea here.
I really like viz.js but I have no idea how easy it would be to make a plugin for Antora with it.
For the moment maybe we can just add this to the contributor documentation:
To create dot diagrams install graphviz sudo dnf install graphviz
sudo dnf install graphviz
create your dot diagram file and then render it dot -T png:cairo Some-diagram.dot > Some-diagram.png
dot -T png:cairo Some-diagram.dot > Some-diagram.png
Off course having a separate dot files for diagrams is not as cool as asciidoctor-diagram gem
@ojn Thanks for your comments, I appreciate someone taking interest in this. Now that I understand how Antora works, I agree that it's not worth integrating a PlantUML server. I don't think it's worth updating the contributor docs because it makes more sense to continue to use readthedocs.io.
FWIW, it's ok with me if you close this ticket. As I mentioned in https://discussion.fedoraproject.org/t/on-the-appropriate-use-of-antora/755 IMHO, there is no reason to use Antora as anything more than a "Jenkins" for text files...
I'm unsure to understand where we are now about this subject. Please remember any content need for these tools suggested should be translatable using po4a.
You may really easily test with a single file: convert source to pot, then copy/paste pot to lang.po, edit lang.po with lokalize or poedit, then convert lang.po to source.lang. If this works, then it's compatible with our tooling.
Further discussion about this issue at Fedora Discussion: Adding diagrams to docs, including test code where I got such feature working.
Login to comment on this ticket.