From nobody Tue Nov 5 12:48:32 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1586630074; cv=none; d=zohomail.com; s=zohoarc; b=nsP/baZaA1Mj7DOrHNUmpL24C44XIuBFDVFbkX0Rv1m20ZJINyx0g0/5cJp3yVvTdK6wtH7QW8RnPkvJIQP83xPulFMrcf9Up0RHpAaNEP1pCQYUd7Y4TkAGmGzDVyjzrDeJxTdZUzzGb04oPo+kUXa1wdjDDNpBY3Q46tIRhig= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1586630074; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=CRIV+Q39jqb8M8RfkaJ8QOUQyFaSY22+KDzJSczZeRM=; b=M8nwtns2k6oD8LYh+sTJvUfJBLX7hccDERkpgbfPVgdEjEIZ8rm8OoTlQcVZ8mvrKTDlQjMclI7I5/u7GlCOYqBPK+huxu8l7XRbgg1MnMs7FGeI74s5bhvMOORHuEJarvgSaAEauesQUmiIThPSmE4iEdFqIagYmizs1DBSOQQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1586630074468430.1013737784365; Sat, 11 Apr 2020 11:34:34 -0700 (PDT) Received: from localhost ([::1]:54672 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jNKxd-00018Q-3Y for importer@patchew.org; Sat, 11 Apr 2020 14:34:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34770) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jNKsv-000658-KU for qemu-devel@nongnu.org; Sat, 11 Apr 2020 14:29:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jNKsu-0003PG-Hl for qemu-devel@nongnu.org; Sat, 11 Apr 2020 14:29:41 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:46602) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jNKsu-0003Oo-Br for qemu-devel@nongnu.org; Sat, 11 Apr 2020 14:29:40 -0400 Received: by mail-wr1-x444.google.com with SMTP id f13so5759904wrm.13 for ; Sat, 11 Apr 2020 11:29:40 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id 68sm8910939wrm.65.2020.04.11.11.29.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 11 Apr 2020 11:29:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=CRIV+Q39jqb8M8RfkaJ8QOUQyFaSY22+KDzJSczZeRM=; b=lMys+IwJxhrC+8ZIvO+0LQ4mvYqexwpWYwlJYuD70iAq/cg7iCz2oJrQLZ9XSt6Nc5 31BY+UGiDujpQ2Chnp6YHtbNhgcZcEYU/5sBSDx44tnphuZPT6K+2RsZU9pDXJFQRg9G DD4RIxceu/bbqZF2AHFhSSOXZ8ydpY0vfN7oo0vfnrdW2ZcYKV14TPlMLnzWv7Jf0sAf 0cKBvhuMaWst74NHy2HLZCCoM/qK4GkMMal0kseTi5wYmKducwTMMBPfwviesB3a2687 dayjWZUe9FHCheCGTHntuCuFcPAYPnWnijIP8UaDBPRPmXbhBBsQPLDEMaRWHRpiMxlH Y6Lg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=CRIV+Q39jqb8M8RfkaJ8QOUQyFaSY22+KDzJSczZeRM=; b=PO+8thH9R4hAcCsuYGZ7n54Qk506oGFpx1OvgAYW4udIr9bnwHZOaqUuBrAw1ucAPz t9+WVAwJJIogtFbWbBkZS2dICSXE0OIym9irXDbEdM2ypJTYzORhpIL2qqFlH2llqjXR pEtpwAyuLaQl7Wn64WrfkfeV2yDar9LnsFRWx51UZXRCYKR4+aMt9Kpy1N2H9QdbqiNQ sRQVlgFNddzDLc7bYwVpKnrLH6crYTDv3B+wxQItUnvuJRRPRQo3FmhpWlHgm29RuREH Nm3/nk7QNubA/er41MtmTcKbBandmAckt2qRj9npQO+Ymhyuj+pWrOm7MojOSNDZ14WM LmyA== X-Gm-Message-State: AGi0PuYteW706U085Y544uwl6/sSX5JexurLfyF07fs9H6fXOFPR43Xa pO13sQxGeil4Erj4p2DAM8fAo3zyIwj9IQ== X-Google-Smtp-Source: APiQypIGoQJMif1oQv2gaa57GdIrEaP9MnadTHStUMu7JLcCjiWU0bbd/d7llGjOP021bITS3yrZ1w== X-Received: by 2002:a05:6000:110a:: with SMTP id z10mr7458968wrw.389.1586629779066; Sat, 11 Apr 2020 11:29:39 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH for-5.0? 3/3] kernel-doc: Use c:struct for Sphinx 3.0 and later Date: Sat, 11 Apr 2020 19:29:34 +0100 Message-Id: <20200411182934.28678-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200411182934.28678-1-peter.maydell@linaro.org> References: <20200411182934.28678-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" The kernel-doc Sphinx plugin and associated script currently emit 'c:type' directives for "struct foo" documentation. Sphinx 3.0 warns about this: /home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h= :3: WARNING: Type must be either just a name or a typedef-like declaration. If just a name: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name, got keyword:= struct [error at 6] struct MemoryListener ------^ If typedef-like declaration: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name. [error at 21] struct MemoryListener ---------------------^ because it wants us to use the new-in-3.0 'c:struct' instead. Plumb the Sphinx version through to the kernel-doc script and use it to select 'c:struct' for newer versions than 3.0. Fixes: LP:1872113 Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/sphinx/kerneldoc.py | 1 + scripts/kernel-doc | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py index 1159405cb92..3e879402064 100644 --- a/docs/sphinx/kerneldoc.py +++ b/docs/sphinx/kerneldoc.py @@ -99,6 +99,7 @@ class KernelDocDirective(Directive): env.note_dependency(os.path.abspath(f)) cmd +=3D ['-export-file', f] =20 + cmd +=3D ['-sphinx-version', sphinx.__version__] cmd +=3D [filename] =20 try: diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8dc30e01e58..030b5c8691f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -71,6 +71,8 @@ Output selection (mutually exclusive): DOC: sections. May be specified multiple times. =20 Output selection modifiers: + -sphinx-version VER Generate rST syntax for the specified Sphinx versi= on. + Only works with reStructuredTextFormat. -no-doc-sections Do not output DOC: sections. -enable-lineno Enable output of #define LINENO lines. Only works = with reStructuredText format. @@ -286,6 +288,7 @@ use constant { }; my $output_selection =3D OUTPUT_ALL; my $show_not_found =3D 0; # No longer used +my $sphinx_version =3D "0.0"; # if not specified, assume old =20 my @export_file_list; =20 @@ -436,6 +439,8 @@ while ($ARGV[0] =3D~ m/^--?(.*)/) { $enable_lineno =3D 1; } elsif ($cmd eq 'show-not-found') { $show_not_found =3D 1; # A no-op but don't fail + } elsif ($cmd eq 'sphinx-version') { + $sphinx_version =3D shift @ARGV; } else { # Unknown argument usage(); @@ -963,7 +968,16 @@ sub output_struct_rst(%) { my $oldprefix =3D $lineprefix; my $name =3D $args{'type'} . " " . $args{'struct'}; =20 - print "\n\n.. c:type:: " . $name . "\n\n"; + # Sphinx 3.0 and up will emit warnings for "c:type:: struct Foo". + # It wants to see "c:struct:: Foo" (and will add the word 'struct' in + # the rendered output). + if ((split(/\./, $sphinx_version))[0] >=3D 3) { + my $sname =3D $name; + $sname =3D~ s/^struct //; + print "\n\n.. c:struct:: " . $sname . "\n\n"; + } else { + print "\n\n.. c:type:: " . $name . "\n\n"; + } print_lineno($declaration_start_line); $lineprefix =3D " "; output_highlight_rst($args{'purpose'}); --=20 2.20.1