Re: Kernel docs: muddying the waters a bit

[Daniel Vetter]

On Sun, Feb 14, 2016 at 1:57 AM, Keith Packard <keithp@xxxxxxxxxx> wrote:
> Jonathan Corbet <corbet@xxxxxxx> writes:
>
>> Asciidoc is a credible solution to the formatted documentation problem,
>> but it's not the only such; I'd like to be sure that we pick the right
>> one.  I worry that asciidoc seems to be aimed mostly at small documents,
>> and that the project itself seems a little lifeless - it's not a good
>> sign when your main page's link to the repository has been dead for a long
>> time.  (Asciidoctor seems more active, with the Github folks behind it,
>> but that means bringing Ruby into the picture).
>
> I was surprised when one of the asciidoctor developers said that
> asciidoc itself was 'in maintenance mode for existing users'. I've tried
> asciidoctor but never got it to the point where I was happy with the
> results. Having two tools using the same nominal format doesn't seem
> like a great idea to me.
>
> It's also clear from my hacking in asciidoc that docbook is the expected
> target for that tool. I've managed to make direct HTML output usable,
> but LaTeX doesn't work at all. Something which focuses on direct HTML
> (and ePub) output would be pretty nice.
>
>> An alternative we haven't really looked at yet is ReStructuredText (or
>> "RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
>> YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
>> Sphinx is a fairly sophisticated documentation system that uses RST.
>
> I've installed debian's python3-sphinx package; it looks like it doesn't
> have a huge dependency chain below it, which is a nice change.
>
> I translated a fairly long document from asciidoc to rst using pandoc by
> using the docbook output from asciidoc -- pandoc doesn't have a native
> asciidoc reader, only a writer. The result didn't totally suck, although
> I haven't messed with fixing the css or using a different theme at all.
>
> http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html
>
> I installed the sphinxcontrib.fulltoc extension so that the whole TOC
> was visible from each section; this made navigating a lot easier. Having
> search included (if you have javascript) seems like a nice feature.
>
>> Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
>> requirements there.
>
> Having functional native latex output means that even PDF generation is
> lighterweight though.
>
>> It produces integrated, multi-file HTML natively,
>> with a TOC, an index, cross-file cross references, and more.  It can make
>> things like function indexes.  It claims output in epub, docbook, and man
>> (I've not yet messed with those).  The path to PDF is via latex; clearly
>> the docbook path could be used too.
>
> I've tried epub and latex backends; epub seems just fine (it's just
> html, after all). LaTeX works, and generates functional PDF, but I'm
> going to have to spend a bunch of time making it looks nice.
>
> http://keithp.com/~keithp/altusmetrum-sphinx/AltusMetrum.pdf
>
>> So can we discuss?  I'm not saying we have to use Sphinx, but, should we
>> choose not to, we should do so with open eyes and good reasons for the
>> course we do take.  What do you all think?
>
> Having spent the afternoon playing with it, I'm definitely
> impressed. I've spent a ton of time getting asciidoc to generate html
> and pdf that I can tolerate; far too much of that involved hacking XML
> files related to the docbook backend.
>
> Pros
>
>  * Credible HTML output without docbook
>
>  * Credible PDF output without docbook.
>
>  * Constructs a unified set of documents across
>    multiple files.
>
>  * Written in Python (2 or 3)
>
>  * PanDoc already supports rst for both input and output. So, if we get
>    bored with RST, we've got a way out.
>
> Cons
>
>  * Table formatting doesn't seem as sophisticated as asciidoc
>
> Questions
>
>  * Conditional text appears to be harder to manage (I haven't managed to
>    make it work at all).
>
>  * Takes over a directory making building more than one
>    document in a directory hard/impossible? The config file must be
>    named 'conf.py'?

One concern/open I have for pro/cons are the hyperlinks from kerneldoc
comments. Currently we have the postproc hack, iirc Jani's patches
generated links native when extracting the kerneldoc. What's the
solution with spinx?

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?

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.

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch