3 ms·

A problem I find with all of these is how can I render and publish the results somewhere on our corporate infra for everyone to see? And then, how do I ensure t

by wdfx 2y ago

A problem I find with all of these is how can I render and publish the results somewhere on our corporate infra for everyone to see? And then, how do I ensure that the diagram-as-code in the repository is synced with that published render? For example, at $work we use Confluence for documentation - I just don't see any of the solutions mentioned in this thread as being compatible with deploying diagrams to confluence, or indeed any type of CMS. It seems that at a minimum you need some bespoke docs rendering pipeline in every repository which spits our rendered docs and diagrams to some other platform? How does everyone else solve this?

WillAdams 2y ago
This is a problem which Literate Programming can solve: http://literateprogramming.com/ http://literateprogramming.com/ getting folks to actually use that is a totally different problem. I've been using a custom .sty file to do this in a native fashion: https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... so that the source isn't a sea of grey comments: https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.tex https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... but it's early days yet, and the project is niche and my coding style quite prosaic.
8n4vidtmkvmk 2y ago
Our $work let's us embed the dot diagrams in our wiki and just renders them. Maybe look for a plugin for whatever you're using? Failing that, a good build system might help. Like I'm sure you could rig Bazel or even Make to regenerate the PNG/SVG when the input changes.
johntash 2y ago
We have a few workflows at work that use the confluence api to publish pages with dynamic content. It's not super convenient, but was easy enough to set up. We're not using diagram-as-code though. Most of our diagrams are embedded into the confluence page or copied from somewhere else.

by wdfx 2y ago

WillAdams 2y ago

This is a problem which Literate Programming can solve: http://literateprogramming.com/ http://literateprogramming.com/ getting folks to actually use that is a totally different problem. I've been using a custom .sty file to do this in a native fashion: https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... so that the source isn't a sea of grey comments: https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.tex https://github.com/WillAdams/gcodepreview/blob/main/gcodepre... but it's early days yet, and the project is niche and my coding style quite prosaic.

8n4vidtmkvmk 2y ago

Our $work let's us embed the dot diagrams in our wiki and just renders them. Maybe look for a plugin for whatever you're using? Failing that, a good build system might help. Like I'm sure you could rig Bazel or even Make to regenerate the PNG/SVG when the input changes.

johntash 2y ago

We have a few workflows at work that use the confluence api to publish pages with dynamic content. It's not super convenient, but was easy enough to set up. We're not using diagram-as-code though. Most of our diagrams are embedded into the confluence page or copied from somewhere else.