From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752358AbeAJW0y (ORCPT + 1 other); Wed, 10 Jan 2018 17:26:54 -0500 Received: from out3-smtp.messagingengine.com ([66.111.4.27]:36313 "EHLO out3-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751561AbeAJW0v (ORCPT ); Wed, 10 Jan 2018 17:26:51 -0500 X-ME-Sender: Date: Thu, 11 Jan 2018 09:26:47 +1100 From: "Tobin C. Harding" To: Jonathan Corbet Cc: "Paul E. McKenney" , Josh Triplett , Linux docs , LKML Subject: Re: [RFC] doc: fix code snippet build warnings Message-ID: <20180110222647.GB23786@eros> References: <1515557093-7036-1-git-send-email-me@tobin.cc> <20180110145958.5b183308@lwn.net> <20180110222531.GA23786@eros> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20180110222531.GA23786@eros> X-Mailer: Mutt 1.5.24 (2015-08-30) User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: 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" 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 > > > --- > > > > > > 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.