From patchwork Wed Feb 14 18:40:09 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 128377 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp911653ljc; Wed, 14 Feb 2018 10:40:45 -0800 (PST) X-Google-Smtp-Source: AH8x227aB+2uvOSQsclvL0MxQyL5CJO+x6kNjUvKidgDeJNxoPeyIjTz49wby7La/Sh5Fi13mgOD X-Received: by 10.99.120.65 with SMTP id t62mr113726pgc.125.1518633645147; Wed, 14 Feb 2018 10:40:45 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518633645; cv=none; d=google.com; s=arc-20160816; b=xQRI8k5PqY/Vo5MjuXeMCKS4Avp8gu46CQMKqYx/4yOgZpVis3dKvo3OacQidXd8fZ pK3i6O/kFYYpa21gGu3mjXUf6F46TO0tNRO5Or5z+A2m1C3ivP61kVPPdxP9/IsgRRzH RWaf3gh2TeNQl/XY0iY8t7BN8d/Qthhb3tACy6c+BigsKCyRjkXJ7NT8Yr5c0HFtGkTY kPEVINYiOyEp3pWqiZwLpuvflNEcfIdR0j+ZH3m6VpvKz2FwBkL5UvcDlG8XlthPbOiR kqI2VjO8krwWpXGXGAc38DDziUG4f98w0Fg4NNoeib3mNk3kTLCZbuk551GIeplr5e4t o9xQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:arc-authentication-results; bh=EoV3QGd6TD3g1PifcVcBp9GmkDYoYtKqWQFXIUB9eqE=; b=kuh6gwpLdQs5PwBfRTdO33+zl6XYIxKmrld37D5sCzhyeet3PJXXNZnuKRF2Fszy9o jXdCDqj5bqxXbSz99VDUY0y3oH5j2iL2b1WfY5iKoM9RxQ0ObtnigEaEuc/nHQbutG8n oK5/Cf7dCxwtF9ZZbTamrV50Q872pqrorIWkq6XzBsA58qRE64J2H/52+KFJNQIC8l2N 7KoSTb+eAo+2SvlwBxQmQoPeidD1Slgu7yc6z1eW3AqeyeK0O1SsLXhCakDBpCKkS9FM n6XO/gFUk5taGJ5TofRKSWFgYoEwM8wB85uQCvMBVqq84dSf9Zaxx3ngUYAuxNDJSJzr 7jzw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id v30si1598337pgo.360.2018.02.14.10.40.44; Wed, 14 Feb 2018 10:40:45 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1162267AbeBNSkj (ORCPT + 28 others); Wed, 14 Feb 2018 13:40:39 -0500 Received: from ms.lwn.net ([45.79.88.28]:54716 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1162237AbeBNSkf (ORCPT ); Wed, 14 Feb 2018 13:40:35 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id A9FCC30A; Wed, 14 Feb 2018 18:40:34 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, jani.nikula@linux.intel.com, Jonathan Corbet Subject: [PATCH 8/8] docs: kernel-doc: Don't mangle literal code blocks in comments Date: Wed, 14 Feb 2018 11:40:09 -0700 Message-Id: <20180214184009.12657-9-corbet@lwn.net> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180214184009.12657-1-corbet@lwn.net> References: <20180214184009.12657-1-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org It can be useful to put code snippets into kerneldoc comments; that can be done with the "::" operator at the end of a line like this:: if (desperate) run_in_circles(); The ".. code-block::" directive can also be used to this end. kernel-doc currently fails to understand these literal blocks and applies its normal markup to them, which is then treated as literal by sphinx. The result is unsightly markup instead of a useful code snippet. Apply a hack to the output code to recognize literal blocks and avoid performing any special markup on them. It's ugly, but that means it fits in well with the rest of the script. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-) -- 2.14.3 Reviewed-by: Jani Nikula diff --git a/scripts/kernel-doc b/scripts/kernel-doc index fb8fbdb25036..cbe864e72a2f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -748,14 +748,73 @@ sub output_blockhead_rst(%) { } } -sub output_highlight_rst { - my $contents = join "\n",@_; - my $line; - +# +# Apply the RST highlights to a sub-block of text. +# +sub highlight_block($) { + # The dohighlight kludge requires the text be called $contents + my $contents = shift; eval $dohighlight; die $@ if $@; + return $contents; +} - foreach $line (split "\n", $contents) { +# +# Regexes used only here. +# +my $sphinx_literal = '^[^.].*::$'; +my $sphinx_cblock = '^\.\.\ +code-block::'; + +sub output_highlight_rst { + my $input = join "\n",@_; + my $output = ""; + my $line; + my $in_literal = 0; + my $litprefix; + my $block = ""; + + foreach $line (split "\n",$input) { + # + # If we're in a literal block, see if we should drop out + # of it. Otherwise pass the line straight through unmunged. + # + if ($in_literal) { + if (! ($line =~ /^\s*$/)) { + # + # If this is the first non-blank line in a literal + # block we need to figure out what the proper indent is. + # + if ($litprefix eq "") { + $line =~ /^(\s*)/; + $litprefix = '^' . $1; + $output .= $line . "\n"; + } elsif (! ($line =~ /$litprefix/)) { + $in_literal = 0; + } else { + $output .= $line . "\n"; + } + } else { + $output .= $line . "\n"; + } + } + # + # Not in a literal block (or just dropped out) + # + if (! $in_literal) { + $block .= $line . "\n"; + if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { + $in_literal = 1; + $litprefix = ""; + $output .= highlight_block($block); + $block = "" + } + } + } + + if ($block) { + $output .= highlight_block($block); + } + foreach $line (split "\n", $output) { print $lineprefix . $line . "\n"; } }