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. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
