lkml.org 
[lkml]   [2018]   [Jan]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    SubjectRe: [RFC] doc: fix code snippet build warnings
    From
    Date

    > Am 16.01.2018 um 11:22 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
    >
    > On Wed, 10 Jan 2018, Jonathan Corbet <corbet@lwn.net> wrote:
    >> On Wed, 10 Jan 2018 15:04:53 +1100
    >> "Tobin C. Harding" <me@tobin.cc> wrote:
    >>
    >>> Posting as RFC in the hope that someone knows how to massage sphinx
    >>> correctly to fix this patch.
    >>>
    >>> Currently function kernel-doc contains a multi-line code snippet. This
    >>> is causing sphinx to emit 5 build warnings
    >>>
    >>> WARNING: Unexpected indentation.
    >>> WARNING: Unexpected indentation.
    >>> WARNING: Block quote ends without a blank line; unexpected unindent.
    >>> WARNING: Block quote ends without a blank line; unexpected unindent.
    >>> WARNING: Inline literal start-string without end-string.
    >>>
    >>> And the snippet is not rendering correctly in HTML.
    >>>
    >>> We can stop shpinx complaining by using '::' instead of the currently
    >>> used '``' however this still does not render correctly in HTML. The
    >>> rendering is [arguably] better but still incorrect. Sphinx renders two
    >>> function calls thus:
    >>>
    >>> :c:func:`rcu_read_lock()`;
    >>>
    >>> The rest of the snippet does however have correct spacing.
    >>
    >> The behavior when `` was used is not surprising, that really just does a
    >> font change. Once you went with a literal block (with "::") though, the
    >> situation changes a bit. That really should work.
    >>
    >> I looked a bit. This isn't a sphinx (or "shpinx" :) problem, the bug is
    >> in kernel-doc. Once we go into the literal mode, it shouldn't be
    >> screwing around with the text anymore. Of course, kernel-doc doesn't
    >> understand enough RST to know that. I'm a little nervous about trying to
    >> teach it more, but maybe we have to do that; we should certainly be able
    >> to put code snippets into the docs and have them come through unmolested.
    >
    > I think eventually the Right Thing would be to move most of kernel-doc's
    > mucking of the comments (i.e. highlights) into kernel-doc the Sphinx
    > extension. I've toyed with the idea, but it's not as trivial as I would
    > like it to be.
    >
    > Basically it involves flagging all the kernel-doc nodes during the read
    > phase, and registering handlers to post process the doctrees. At that
    > stage, it's no longer simple regexp replaces, it's replacing doctree
    > nodes with ones that have reference nodes within them. It's more
    > complicated,

    Hi Jani, my thoughts about:

    1.) The reST syntax [1] (the parser part) is not *extendable*, we
    can only add new roles [2] or directives.

    2.) the kernel-doc syntax is weak and ambiguous. This
    remains mainly in tagging only with a start-tag or only with a end-tag
    e.g:

    * sectioning: "Return:" --> end-tag just ":"
    * fields: "@arg1:" --> better
    * highlight/ref: start tag [@%$&] / no end tag

    even if I don't know how (1.), if the highlight-syntax becomes a part
    of the reST syntax we have to quote [@%$&] elsewhere. This will break
    with valid reST documents which is unacceptable.

    Thats why I think we need to pre-parse highlighting in the kernel-doc
    Perl script, even if it is a bit hackish (how should it be otherwise,
    if the syntax is already hackish). I haven't had the time to implement
    such a highlight parser right now, but this would be the first shot of
    mine.

    An alternative might be to use roles [2] but this means we have to
    break with the the kernel-doc (highlight) syntax which is IMO also
    unacceptable ... tricky situation :o

    [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
    [2] http://docutils.sourceforge.net/docs/howto/rst-roles.html


    > but at that stage we can ignore stuff that should stay
    > verbatim. I think it's also possible to check that the reference targets
    > actually exist. In short, at that phase we have all the knowledge about
    > the rst structure, parsed by Sphinx, and we don't have to duplicate that
    > knowledge in kernel-doc the perl script.
    >
    > Note that this has nothing to do with swithing to Python based
    > kernel-doc suggested by Markus previously.

    ;)

    -- Markus --

    \
     
     \ /
      Last update: 2018-01-16 13:36    [W:2.629 / U:0.628 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site