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

[Tobin C. Harding]

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

Woops, not 're-spin' - we are on an RFC.  I'll wait for your response
then submit a PATCH

thanks,
Tobin.