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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to