[openstack-dev] [nova][all] Architecture Diagrams in ascii art?
dborodaenko at mirantis.com
Sat Jun 6 00:32:19 UTC 2015
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
You're right, in my experience blogdiag is useless even for relatively
Lately I've been using ascii2svg  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 , here's how the result looks in PDF . I've also included
rendered files in the git repo , so that one doesn't have to install
a2s to update the text. Same approach can work just as fine with Sphinx.
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.
More information about the OpenStack-dev