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

[Tobin C. Harding]

On Wed, Jan 10, 2018 at 02:59:58PM -0700, Jonathan Corbet wrote:
> On Wed, 10 Jan 2018 15:04:53 +1100
> "Tobin C. Harding" <me@xxxxxxxx> wrote:
> 
> > Posting as RFC in the hope that someone knows how to massage sphinx
> > correctly to fix this patch.
> > 
> > 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.
> 
> The behavior when `` was used is not surprising, that really just does a
> font change.  Once you went with a literal block (with "::") though, the
> situation changes a bit.  That really should work.
> 
> I looked a bit.  This isn't a sphinx (or "shpinx" :) problem, the bug is
> in kernel-doc.  Once we go into the literal mode, it shouldn't be
> screwing around with the text anymore.  Of course, kernel-doc doesn't
> understand enough RST to know that.  I'm a little nervous about trying to
> teach it more, but maybe we have to do that; we should certainly be able
> to put code snippets into the docs and have them come through unmolested.
> 
> I'll try to look more closely at that shortly.  Meanwhile, this patch
> makes things better than the were before.  That said...
> 
> > Use '::' to pre-fix code snippet. Clears build warnings but does not
> > render correctly.
> > 
> > Signed-off-by: Tobin C. Harding <me@xxxxxxxx>
> > ---
> > 
> > To view current broken rendering see
> > 
> > https://www.kernel.org/doc/html/latest/core-api/kernel-api.html?highlight=rcu_pointer_handoff#c.rcu_pointer_handoff
> > 
> >  include/linux/rcupdate.h | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> > 
> > diff --git a/include/linux/rcupdate.h b/include/linux/rcupdate.h
> > index a6ddc42f87a5..cc10e772e3e9 100644
> > --- a/include/linux/rcupdate.h
> > +++ b/include/linux/rcupdate.h
> > @@ -568,7 +568,8 @@ static inline void rcu_preempt_sleep_check(void) { }
> >   * is handed off from RCU to some other synchronization mechanism, for
> >   * example, reference counting or locking.  In C11, it would map to
> >   * kill_dependency().  It could be used as follows:
> > - * ``
> > + * ::
> 
> ...rather than adding a separate "::" line, you can just
> s/follows:/follows::/ and the Right Thing will happen (to the same extent
> that it does now, anyway.

Except that it will render as

	kill_dependency().  It could be used as follows

instead of
	kill_dependency().  It could be used as follows:

(note: final colon)

Also the diff will be bigger.  These two reasons led me to the patch as
it is.  I'm happy to re-spin with your suggested change though.

thanks,
Tobin.