Messages in this thread | | | From | Keith Packard <> | Subject | Re: Kernel docs: muddying the waters a bit | Date | Sun, 14 Feb 2016 08:27:23 -0800 |
| |
Daniel Vetter <daniel.vetter@ffwll.ch> writes:
> The other one is graphs - Keith showed me some neat stuff that > asciidoc can do, and I definitely wanted to integrate something like > that as a follow-up into the kerneldoc toolchain. Often a diagram is a > lot more helpful than lots of words. Can sphinx gives us that too?
.. graphviz::
digraph foo { "bar" -> "baz"; }
Even better than asciidoc -- svg output is supported in both html and pdf (when using rst2pdf). I had to hack asciidoc to add support for svg output when using docbook.
> Wrt reformatting: I'm not going to like it, but I hope that with a bit > of sed we can fix up any of the asciidoc comments we have already > easily - right now we don't (yet) use much of the more sophisticated > markup yet. So much better to change now than 1 year down the road.
I used pandoc on the docbook output from asciidoc to get a 100 page document converted here. It wasn't perfect -- all of the internal links were busted, and labels for tables were mis-positioned. It might be that a few minor fixes to pandoc could be done to add 'sphinx'-specific rst support that could fix this?
I spent (too much) time yesterday playing with sphinx and generated a new html theme. Here's the result:
http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html
Here's the PDF output from rst2pdf, a python-based PDF output which doesn't use docbook *or* latex:
http://keithp.com/~keithp/altusmetrum-sphinx/Altus%20Metrum.pdf
I need to spend some quality time building my own PDF theme; the default provided by rst2pdf isn't great. It does, however, use fontconfig, so switching fonts is *way* easier than with docbook...
There's currently an incompatibility between the rst2pdf and sphnix packages in debian (and upstream) which I hacked around to generate that output, but otherwise I'm using packaged bits.
So, another pro for sphinx appears to be native PDF generation...
-- -keith [unhandled content-type:application/pgp-signature] | |