Sequence diagrams not showing in markdown files
elnyry-sam-k opened this issue · comments
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:
- 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
- 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 %}
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).
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..
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)