From mboxrd@z Thu Jan  1 00:00:00 1970
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1752345AbeAJUaO (ORCPT <rfc822;ralf@linux-mips.org> + 1 other);
        Wed, 10 Jan 2018 15:30:14 -0500
Received: from out3-smtp.messagingengine.com ([66.111.4.27]:42555 "EHLO
        out3-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK)
        by vger.kernel.org with ESMTP id S1751668AbeAJUaM (ORCPT
        <rfc822;linux-kernel@vger.kernel.org>);
        Wed, 10 Jan 2018 15:30:12 -0500
X-ME-Sender: <xms:03dWWlKbdozSrXJAMItQ7YIn5mxJFA8j4L60cWuFx-RVzwfE97KRqQ>
Date: Thu, 11 Jan 2018 07:30:07 +1100
From: "Tobin C. Harding" <me@tobin.cc>
To: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
        Josh Triplett <josh@joshtriplett.org>,
        Linux docs <linux-doc@vger.kernel.org>,
        LKML <linux-kernel@vger.kernel.org>
Subject: Re: [RFC] doc: fix code snippet build warnings
Message-ID: <20180110203007.GB25272@eros>
References: <1515557093-7036-1-git-send-email-me@tobin.cc>
 <20180110163702.GF9671@linux.vnet.ibm.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20180110163702.GF9671@linux.vnet.ibm.com>
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: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Return-Path: <linux-kernel-owner@vger.kernel.org>

On Wed, Jan 10, 2018 at 08:37:02AM -0800, Paul E. McKenney wrote:
> 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.  ;-)

Besides making me laugh out loud I did not think of this issue while
patching. FWIW, now you have mentioned it, I favour noisy errors :)

thanks,
Tobin.