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

[Jonathan Corbet]

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.

Thanks,

jon