Sequence diagrams not showing in markdown files

[elnyry-sam-k]

Describe the bug
The sequence diagrams that are based on plantuml files are not available on the markdown version of the docs such as the API Definition.

For example figure-50 on the API Definition v1.1 markdown file: https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/API-Definition_v1.1.1.md#figure-50

Notes: Since gitbooks has been chosen for rendering documentation, the scripts we have automatically generate svgs for plantuml diagrams when we create a release and then publish to git books. This is part of the CI/CD process.

There are two types of diagrams in the current docs, sequence diagrams that use plantuml and then other hand drawn diagrams, to represent state transitions etc (that are not plantuml); Both types of diagrams show fine on gitbooks: https://docs.mojaloop.io/api/fspiop/v1.1/api-definition.html#figure-50

This may technically not be a bug but more of an experience issue (as it is by design), but logging this to discuss ways to enhance the experience around plain markdown files

Priority & Severity:
Priority: Low
Severity: Low

To Reproduce
Steps to reproduce the behavior:

1. Go to figure-50 on the API Definition v1.1 markdown file: https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/API-Definition_v1.1.1.md#figure-50
2. There is no svg available (by design)

Expected behavior
To be decided - should there be an SVG or a diagram available even on the markdown file (discuss)

Screenshots
Not. a screenshot, but this is how it shows up currently (on the md files)

figure 50
{% uml src="assets/diagrams/sequence/figure50.plantuml" %} {% enduml %}

[lewisdaly]

We have some pretty handy tools for rendering .svgs from puml sources in the documentation repo we could borrow from. That would require keeping .svgs in git (which I don't think is all that bad).

[elnyry-sam-k]

Can we discuss this @lewisdaly , AFAIK this repo replicated the tooling from the documentation repo (at least, at the time).. It would be great of course to have the tools there anyway, and having SVGs should be fine and will help fix this issue..

[millerabel]

I would have said we want several characteristics... Developers can preview changes to seq diags when working offline ... that is, previewing a revised Markdown file offline shows the latest local UML JIT compiled to SVG within the preview. (Or built in a simple makefile or script.) PR and Build processes should actively compile to SVG to be sure nothing is broken in the build. Online viewers of Markdown content see the properly tagged version of UML in context with the doc they are reading. The first of these suggests a command line preview tool and local UML compiler; ideally without running the PlantUML proxy on localhost, though, then again, maybe that is a solution. It also suggests that URLs in Markdown files are relative to the local code tree so I can preview local changes. (I’m noting that the hosted PlantUML proxy service requires an absolute URL and will pull from GtiHub if properly setup, but would require a different method to preview tree-relative content.) — Miller On Apr 1, 2021, at 3:24 AM, Sam ***@***.***> wrote:  Can we discuss this @lewisdaly , AFAIK this repo replicated the tooling from the documentation repo (at least, at the time).. It would be great of course to have the tools there anyway, and having SVGs should be fine and will help fix this issue.. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[elnyry-sam-k]

Thanks Miller, agree with the requirements.. For the first one though (local development), I use VS code and a plugin/extension for that which quickly renders an SVG and we already have CI/CD steps that build/validate SVG generation for plantuml files (for docs repos)... Will work with Lewis to fill the gaps (image in markdown file, etc)

[millerabel]

Hi Sam, I think the challenge is the URL in the MD files is to public endpoints on GitHub. They don’t reference the local SVG I might have just rendered. So if the URLs can be relative, they would pull from local file system. CommonMark viewer (or an editor plug-in) would allow previewing the MD content, with updated diagrams, before a PR is submitted. Not sure if we consistently use relative urls in the md files.

…

-- Miller On Apr 14, 2021, at 12:51 PM, Sam ***@***.***> wrote:  Thanks Miller, agree with the requirements.. For the first one though (local development), I use VS code and a plugin/extension for that which quickly renders an SVG and we already have CI/CD steps that build/validate SVG generation for plantuml files (for docs repos)... — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.