Re: Kernel docs: muddying the waters a bit

[Daniel Vetter]

Hi all,

So sounds like moving ahead with rst/sphinx is the option that should
allow us to address everyone's concerns eventually? Of course the
first one won't have it all (media seems really tricky), but I'd like
to get something awesome in this area closer to mainline. I'm stalling
on typing more fancyful gpu docs right now (with tables, pictures and
stuff) since that would require a pile of needless work to redo when
we switch a few times more ;-)

And Jani also wants to get this in, but he doesn't really want to
spend more effort on a system that can't be merged.

So sphinx/rst y/n? Jon, is that ok with you from the doc maintainer pov?

Cheers, Daniel

On Wed, Apr 27, 2016 at 4:28 PM, Grant Likely <grant.likely@xxxxxxxxxxxx> wrote:
> On Tue, Apr 12, 2016 at 4:46 PM, Jonathan Corbet <corbet@xxxxxxx> wrote:
>> On Fri, 8 Apr 2016 17:12:27 +0200
>> Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
>>
>>> motivated by this MT, I implemented a toolchain to migrate the kernelâs
>>> DocBook XML documentation to reST markup.
>>>
>>> It converts 99% of the docs well ... to gain an impression how
>>> kernel-docs could benefit from, visit my sphkerneldoc project page
>>> on github:
>>>
>>>   http://return42.github.io/sphkerneldoc/
>>
>> So I've obviously been pretty quiet on this recently.  Apologies...I've
>> been dealing with an extended death-in-the-family experience, and there is
>> still a fair amount of cleanup to be done.
>>
>> Looking quickly at this work, it seems similar to the results I got.  But
>> there's a lot of code there that came from somewhere?  I'd put together a
>> fairly simple conversion using pandoc and a couple of short sed scripts;
>> is there a reason for a more complex solution?
>>
>> Thanks for looking into this, anyway; I hope to be able to focus more on
>> it shortly.
>
> Hi Jon,
>
> Thanks for digging into this. FWIW, here is my $0.02. I've been
> working on restarting the devicetree specification, and after looking
> at both reStructuredText and Asciidoc(tor) I thought I liked the
> Asciidoc markup better, so chose that. I then proceeded to spend weeks
> trying to get reasonable output from the toolchain. When I got fed up
> and gave Sphinx a try, I was up and running with reasonable PDF and
> HTML output in a day and a half.
>
> Honestly, in the end I think we could make either tool do what is
> needed of it. However, my impression after trying to do a document
> that needs to have nice publishable output with both tools is that
> Sphinx is easier to work with, simpler to extend, better supported. My
> vote is firmly behind Sphinx/reStructuredText.
>
> g.



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