lkml.org 
[lkml]   [2018]   [Jan]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RFC] doc: fix code snippet build warnings
On Thu, Jan 11, 2018 at 09:25:31AM +1100, Tobin C. Harding wrote:
> On Wed, Jan 10, 2018 at 02:59:58PM -0700, Jonathan Corbet 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'll try to look more closely at that shortly. Meanwhile, this patch
> > makes things better than the were before. That said...
> >
> > > Use '::' to pre-fix code snippet. Clears build warnings but does not
> > > render correctly.
> > >
> > > Signed-off-by: Tobin C. Harding <me@tobin.cc>
> > > ---
> > >
> > > To view current broken rendering see
> > >
> > > https://www.kernel.org/doc/html/latest/core-api/kernel-api.html?highlight=rcu_pointer_handoff#c.rcu_pointer_handoff
> > >
> > > include/linux/rcupdate.h | 4 ++--
> > > 1 file changed, 2 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
> > > index a6ddc42f87a5..cc10e772e3e9 100644
> > > --- a/include/linux/rcupdate.h
> > > +++ b/include/linux/rcupdate.h
> > > @@ -568,7 +568,8 @@ static inline void rcu_preempt_sleep_check(void) { }
> > > * is handed off from RCU to some other synchronization mechanism, for
> > > * example, reference counting or locking. In C11, it would map to
> > > * kill_dependency(). It could be used as follows:
> > > - * ``
> > > + * ::
> >
> > ...rather than adding a separate "::" line, you can just
> > s/follows:/follows::/ and the Right Thing will happen (to the same extent
> > that it does now, anyway.
>
> Except that it will render as
>
> kill_dependency(). It could be used as follows
>
> instead of
> kill_dependency(). It could be used as follows:
>
> (note: final colon)
>
> Also the diff will be bigger. These two reasons led me to the patch as
> it is. I'm happy to re-spin with your suggested change though.

Woops, not 're-spin' - we are on an RFC. I'll wait for your response
then submit a PATCH

thanks,
Tobin.

\
 
 \ /
  Last update: 2018-01-14 23:22    [W:1.582 / U:0.460 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site