From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S966346AbeAJQg2 (ORCPT + 1 other); Wed, 10 Jan 2018 11:36:28 -0500 Received: from mx0a-001b2d01.pphosted.com ([148.163.156.1]:37698 "EHLO mx0a-001b2d01.pphosted.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S966318AbeAJQgX (ORCPT ); Wed, 10 Jan 2018 11:36:23 -0500 Date: Wed, 10 Jan 2018 08:37:02 -0800 From: "Paul E. McKenney" To: "Tobin C. Harding" Cc: Jonathan Corbet , Josh Triplett , Linux docs , LKML Subject: Re: [RFC] doc: fix code snippet build warnings Reply-To: paulmck@linux.vnet.ibm.com References: <1515557093-7036-1-git-send-email-me@tobin.cc> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1515557093-7036-1-git-send-email-me@tobin.cc> User-Agent: Mutt/1.5.21 (2010-09-15) X-TM-AS-GCONF: 00 x-cbid: 18011016-0048-0000-0000-000002225946 X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00008354; HX=3.00000241; KW=3.00000007; PH=3.00000004; SC=3.00000245; SDB=6.00973042; UDB=6.00492998; IPR=6.00752992; BA=6.00005772; NDR=6.00000001; ZLA=6.00000005; ZF=6.00000009; ZB=6.00000000; ZP=6.00000000; ZH=6.00000000; ZU=6.00000002; MB=3.00018963; XFM=3.00000015; UTC=2018-01-10 16:36:20 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 18011016-0049-0000-0000-000043BAABC0 Message-Id: <20180110163702.GF9671@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2018-01-10_08:,, signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 impostorscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1709140000 definitions=main-1801100232 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: 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 > --- > > 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 >