Re: [RFC] doc: fix code snippet build warnings

From: Tobin C. Harding
Date: Wed Jan 10 2018 - 15:30:17 EST


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.