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