Open Stack

On Fri, May 15, 2015 at 06:33:35PM -0700, Joe Gordon wrote:
> On Fri, May 15, 2015 at 2:27 PM, Joe Gordon <joe.gordon0 at gmail.com> wrote:
> > On Thu, May 14, 2015 at 3:52 AM, John Garbutt <john at johngarbutt.com>
> > wrote:
> >> Some great points make here.
> >>
> >> Lets try decide something, and move forward here.
> >>
> >> Key requirements seem to be:
> >> * we need something that gives us readable diagrams
> >> * if its not easy to edit, it will go stale
> >> * ideally needs to be source based, so it lives happily inside git
> >> * needs to integrate into our sphinx pipeline
> >> * ideally have an opensource editor for that format (import and
> >> export), for most platforms
> >>
> >> ascii art fails on many of these, but its always a trade off.
> >>
> >> Possible way forward:
> >> * lets avoid merging large hard to edit bitmap style images
> >> * nova-core reviewers can apply their judgement on merging source based
> >> formats
> >> * however it *must* render correctly in the generated html (see result
> >> of docs CI job)
> >>
> >> Trying out SVG, and possibly blockdiag, seem like the front runners.
> >> I don't think we will get consensus without trying them, so lets do that.
> >>
> >> Will that approach work?
> >>
> > Sounds like a great plan.
> 
> After further investigation in blockdiag, is useless for moderately complex
> diagrams.

You're right, in my experience blogdiag is useless even for relatively
simple diagrams.

Lately I've been using ascii2svg [0] with great success, it allows you
to have fairly complex freeform ascii art diagrams that render quite
nicely into SVG. As an example, here's how I integrated it into LaTeX
beamer [1], here's how the result looks in PDF [2]. I've also included
rendered files in the git repo [3], so that one doesn't have to install
a2s to update the text. Same approach can work just as fine with Sphinx.

[0] http://9vx.org/~dho/a2s/
[1] https://github.com/angdraug/beamer-fuel-ceph
[2] https://drive.google.com/a/mirantis.com/file/d/0BxYswyvIiAEZUEp4aWJPYVNjeU0
[3] https://github.com/angdraug/beamer-fuel-ceph/blob/master/fuel-components.svg

Before someone comes back to the argument that ascii art limits the
amount of complexity you can cram into a single diagram, I'd like to
point out that after several years of using Enterprise Architect to
maintain interlinked collections of wall-sized UML diagrams, I've come
to realization that when your diagram no longer fits on a terminal
window's worth of ascii art and can't remain legible when you fit it
into a presentation slide, it's too complex to be helpful in
understanding your architecture. When that happens, you have to stay on
a higher abstraction level and have separate diagrams for each lower
level component. If you can't do that, you have to fix the architecture.

-- 
Dmitry Borodaenko