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.gord...@gmail.com> wrote: > > On Thu, May 14, 2015 at 3:52 AM, John Garbutt <j...@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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
