From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751409AbeAPKRP (ORCPT + 1 other); Tue, 16 Jan 2018 05:17:15 -0500 Received: from mga03.intel.com ([134.134.136.65]:32506 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750927AbeAPKRN (ORCPT ); Tue, 16 Jan 2018 05:17:13 -0500 X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,367,1511856000"; d="scan'208";a="22700571" From: Jani Nikula To: Jonathan Corbet , "Tobin C. Harding" Cc: "Paul E. McKenney" , Josh Triplett , Linux docs , LKML Subject: Re: [RFC] doc: fix code snippet build warnings In-Reply-To: <20180110145958.5b183308@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <1515557093-7036-1-git-send-email-me@tobin.cc> <20180110145958.5b183308@lwn.net> Date: Tue, 16 Jan 2018 12:22:01 +0200 Message-ID: <87fu762jee.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: On Wed, 10 Jan 2018, 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 think eventually the Right Thing would be to move most of kernel-doc's mucking of the comments (i.e. highlights) into kernel-doc the Sphinx extension. I've toyed with the idea, but it's not as trivial as I would like it to be. Basically it involves flagging all the kernel-doc nodes during the read phase, and registering handlers to post process the doctrees. At that stage, it's no longer simple regexp replaces, it's replacing doctree nodes with ones that have reference nodes within them. It's more complicated, but at that stage we can ignore stuff that should stay verbatim. I think it's also possible to check that the reference targets actually exist. In short, at that phase we have all the knowledge about the rst structure, parsed by Sphinx, and we don't have to duplicate that knowledge in kernel-doc the perl script. Note that this has nothing to do with swithing to Python based kernel-doc suggested by Markus previously. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center