lkml.org 
[lkml]   [2016]   [Jun]   [7]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    SubjectRe: [PATCH 0/7] add reST/sphinx-doc to linux documentation
    Date
    On Tue, 07 Jun 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
    > I think getting the flat-table directive landed would be great. We
    > have a similarly annoying table in gpu.tmpl where the ascii-art tables
    > fall short and are annoying. We want to split it up, but that's not a
    > short-term solution suitable for conversion. Atm it's licensed under
    > gplv3, which is incompatible with the kernel, so need to fix that.

    Agreed.

    > I'm still not sold on the vintage-kerneldoc idea. At least in my
    > experience (after first converting to asciidoc and now to sphinx) this
    > is a non-issue. Yes, there's the oddball misrendering, but that's no
    > worse than the oddball typo. And a really good way for
    > drive-by-contributors and newbies to send in a few useful patches.
    > Personally I'm totally happy to have that bit of ugliness, same way I
    > don't reject patches just because they trip over checkpatch.pl in some
    > minor detail. The downside otoh means we'll have to forever maintain 2
    > versions of kernel-doc, and I don't want that. Jani&me have already
    > ripped out some of the more bonghits features of kernel-doc (like
    > anything with a \w: is a heading and other nonsense like that). The
    > only thing we really need to keep as special is the overall kerneldoc
    > layout, and the special referencing using &, %, @ and friends.

    Agreed.

    > Reimplementing kernel-doc in python is also something Jani&I
    > discussed. But I think it only makes sense if we go ahead and also
    > modernize the parser, i.e. use something like python-clang to parse C,
    > and build a modern parser-combinators thing for the kernel-doc itself.
    > The regex state machinery is a horror show, whether it's written in
    > cargo-culted perl or python.

    I think the only sensible way to change the parser is to get everything
    working using the perl version first, and then you can diff the results
    against the python version. That's about the only validation of the new
    parser that actually matters in the real world.

    At this time, I'd put this way down in the list of priorities.

    > I agree that we need to update the kernel-doc howto (and Jani's
    > working on that already too), but I think there's no need to split up
    > that finely. Maybe that's a bit against sphinx best practices, but
    > right now we have rather large documents (both plain text and
    > docbook). Splitting definitely makes sense in some cases (e.g.
    > gpu.tmpl is only this large because we couldn't do cross-template
    > referencing), but by-and-large I think the current splitting is mostly
    > reasonable.

    One of the key arguments against too much splitting that hasn't been
    mentioned is that despite all the fine output Sphinx can produce, we
    have plenty of people who couldn't care less about running Sphinx to get
    readable documentation. They will grep and read the plain text files
    directly, and that's a large part of the appeal of any lightweight
    markup.

    When you split up a file into snippets that no longer tell a coherent
    story independently, you've failed.

    For the .txt files under Documentation, we mostly do not want to split
    them up any more if and when they're converted to rst. For the .tmpl
    files under Documentation/DocBook, each rst file split off from there
    should still be a sensible document on its own, with the filename
    telling what it's about. This will be the main benefit of this whole
    exercise for the people who do not care about Sphinx - instead of
    reading (read: ignoring) DocBook XML, they can now read the rst files.

    BR,
    Jani.

    --
    Jani Nikula, Intel Open Source Technology Center

    \
     
     \ /
      Last update: 2016-06-07 11:41    [W:4.189 / U:0.072 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site