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 Wed, Jan 10, 2018 at 08:37:02AM -0800, Paul E. McKenney wrote:
> On Wed, Jan 10, 2018 at 03:04:53PM +1100, Tobin C. Harding wrote:
> > Posting as RFC in the hope that someone knows how to massage sphinx
> > correctly to fix this patch.
>
> I would welcome that. ;-)
>
> > 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.
> >
> > Use '::' to pre-fix code snippet. Clears build warnings but does not
> > render correctly.
>
> If the usual docbook suspects ack this, I would be happy to carry it.
>
> Cue debate over silent vs. noisy errors. ;-)

Besides making me laugh out loud I did not think of this issue while
patching. FWIW, now you have mentioned it, I favour noisy errors :)

thanks,
Tobin.

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