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

[Paul E. McKenney]

On Thu, Jan 11, 2018 at 07:30:07AM +1100, Tobin C. Harding wrote:
> 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 :)

Very good, will leave this one alone, then.  ;-)

							Thanx, Paul