Re: sequence diagrams in rst documentation

[Jonathan Corbet <corbet@lwn.net>]

On Tue, 18 Oct 2016 13:43:41 +0200
Johannes Berg <johannes@sipsolutions.net> wrote:

> > Example here:
> > https://johannes.sipsolutions.net/files/80211/mac80211.html#connection-flow  
> 
> Coming back to this - sadly, it appears that this software (blockdiag,
> seqdiag) is completely unmaintained, with open pull requests dating
> back to 2012 and the last commit dating back to 2015-08-22.
> 
> I'd want/need feature improvements in it too, but if I can't feed those
> back to upstream (since it appears dead), there's little point.
> 
> Perhaps we can ship plugins for this as part of the kernel sources?
> Shouldn't be too difficult to reimplement something like this, after
> all.

OK, I've read through all of this.  My thoughts, for whatever it's worth.

We already carry a few sphinx plugins in the kernel; there is room for
more if we *really* need them.  But...

 - Part of the idea behind switching over to sphinx was to be able to get
   away from maintaining our own formatting system.  Adding plugins to the
   kernel is a step away from that goal.  So I'd like to be sure that
   there's nothing that's part of standard sphinx that will do the job
   first.

That said, I think that requiring people to install plugins from contrib
sites or third-party repos may be even worse.  We don't want to put people
through misery just to format the docs.

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'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...

jon