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. ;-)
Thanx, Paul
> Signed-off-by: Tobin C. Harding <m...@tobin.cc>
> ---
>
> 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:
> - * ``
> + * ::
> + *
> * rcu_read_lock();
> * p = rcu_dereference(gp);
> * long_lived = is_long_lived(p);
> @@ -579,7 +580,6 @@ static inline void rcu_preempt_sleep_check(void) { }
> * p = rcu_pointer_handoff(p);
> * }
> * rcu_read_unlock();
> - *``
> */
> #define rcu_pointer_handoff(p) (p)
>
> --
> 2.7.4
>
--
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
