Graphviz for documentation

Question

I noticed that doxygen uses the graphviz library for creating diagrams. Have you ever used graphviz for generating documentation? Is it worth learning the graphviz for documentation purposes outside the scope of doxygen? Or am I better off to sticking with a standard data modeling package like Visio?

I understand the merits of it as a graphing library, but for trying to represent more complex UML (or similar) is it still worth looking into?

Answer 1

The graphviz is very very simple language/format for creating graphs. If the capabilities are enough for you I would recommend it (Its so easy, that I would estimate the time to learn with at most 1 hour).

Answer 2

If you're just talking about creating inheritance/collaboration diagrams like Doxygen does, it's worth investigating IDEs that will do that for you automatically. For from-scratch or hand-tuned documentation, I use OmniGraffle (since I'm on a Mac) which I highly recommend.

However, GraphViz and DOT can be really handy, not only for documentation, but for debugging and code comprehension as well, particularly for data structures. I generally don't write DOT by hand, but automatically-generated DOT can be well worth the minimal effort.

One of the places I've found GraphViz extremely useful is for understanding and debugging binary search tree algorithms. I develop CHDataStructures.framework, an open-source Objective-C framework, which includes several varieties of BSTs. I implemented two methods: -(NSString*)dotGraphString on the parent class and -(NSString*)dotGraphStringForNode: on each child class. In about 30-40 lines of code (most of it at the bottom of CHAbstractBinarySearchTree.m), I added the ability to iteratively traverse a binary tree and create a DOT representation of it, including balancing information, coloring nodes red or black, etc. (With a little care, you can easily represent null sentinel nodes and display the tree in proper sorted order.)

In my test code, after each modification of the tree, I called -dotGraphString and saved the result to a .dot file, stopped there with a breakpoint, then opened that file with GraphViz, which is smart enough to re-render the DOT graph when the file is updated. This approach made it vastly easier to see what was happening in the tree and spot bugs in my implementation of a given algorithm. This approach can be adapted fairly easily for various kinds of data structures, and is generally much faster and easier than creating a UI just for visualizing the structure.

Answer 3

Graphviz is not going to give you a slick graphical interface like Visio. It will however, produce well laid out graphs. I find it most useful when I am generating graphs automatically via a program (as in the case of doxygen).

Answer 4

Graphviz is most useful to generate dependency graphs (via dot) programmatically. Visitors uses it to visualize site visits; Hadoop/Cascading uses it to visualize execution plan of map-reduce jobs.

Answer 5

I use GraphViz extensively for documentation and often sketch out relationships or architecture diagrams using GraphViz externally then add them to extra pages in my Doxygen code using the @dot/@enddot. I've also recently started using @dotfile which has the dual benefit of keeping large dot statements out of the code docs and allowing me to continue to preview them with the GraphViz GUI.

The other big benefit with GraphViz is that the simple textual format works very well with version control. You can see changes to diagrams in your git diff which would be impossible with any binary documentation format. As I've used it more an more over the years, this is becoming a more important feature to me.

However, for UML I use a true UML tool (Enterprise Architect) rather than stuffing around in Visio.

Answer 6

Yes, graphviz is easy to learn and easy to use from within programs.

Also look at yEd which is a good tool for working with graphs. Unlike Visio, it will load and save a variety of formats which are easy to hand-edit or programatically-generate. The auto-layout stuff is quite nice too.

Answer 7

I've used it occasionally for illustrating state machines. graphviz is perfect for that.

Answer 8

Agree with the consensus here; I get a lot of value out of Graphviz. It's really good for creating simple, and not so simple, diagrams. Software developers tend to attract graphs, not just in source code but elsewhere as well.

For example, right now in another browser window, I have our group's branching and merging strategy illustrated using a graphviz diagram (displayed using the confluence plugin BTW).

Graphviz is good for UML too. See this tutorial; it's a good introduction to Graphviz as well.

Answer 9

We use graphviz to automatically generate object diagrams as feedback of our UML verification tool. We are really happy with the results since we manage to provide a graphical result without worrying at all about the layout.

Answer 10

I had a go with Graphviz quite a few times, though found it quite limiting.

What I found best for manual text-entry diagrams is Tikz I used it for FSM's

If Graphviz output satisfies your particular needs, it's probably fine. If you are not quite happy with what it does and have some TeX experience - have a look at Tikz. There many different packages out there, you don't need to learn pure Tikz/PGF (which may seem quite heavy).

Answer 11

FYI Microsoft Visio addin to layout diagrams with Graphviz: http://www.calvert.ch/graphvizio/