Re: sequence diagrams in rst documentation

[Johannes Berg <johannes@sipsolutions.net>]

On Tue, 2016-10-18 at 17:52 -0600, Jonathan Corbet wrote:

> In summary, I think we can consider taking on a module if it's what
> we need to do the docs right.  And if somebody agrees to maintain it!
> :)

:)

I think for the ones that we carry, they're probably specific?

> I've heard others say they would like better diagramming support.  Do
> you think that, maybe, something like aafigure would do the trick?
> 
> 	https://pythonhosted.org/sphinxcontrib-aafig/
> 
> I've not actually played with it at all, but I like the idea that
> we'd have readable diagrams in the source docs as well...

Well, maybe. I agree having it readable in the source docs as well is
nice, but for sequence diagrams in particular, I don't think

    +-------+         +-----------+
    | Hello +-------->+ aafigure! |
    +-------+         +-----------+

really beats

   Hello -> aafigure!

by much. You could do some alignment even with the latter version, and
the above isn't even really a sequence diagram anyway :)

Some of the sequence diagrams may also be automatically generated from
runtime behaviour observation (e.g. tracing, we've actually done that),
and outputting the types of ascii boxes is much more difficult there.

For other types of diagrams this may be nice though.

Anyway, I guess we'll cross that bridge when we get to it. I'd like to
have these types of documentation, perhaps with a script to auto-
generate from tracing - such as script and visual display can even
serve as a debugging aid :)

johannes