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

[Tobin C. Harding]

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.