Re: sequence diagrams in rst documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux