From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 5A3E2C6FD1F for ; Thu, 16 Mar 2023 13:43:23 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pcnsf-0001Xs-Eg; Thu, 16 Mar 2023 09:42:57 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pcnse-0001XH-5x for qemu-devel@nongnu.org; Thu, 16 Mar 2023 09:42:56 -0400 Received: from mail-pf1-x42c.google.com ([2607:f8b0:4864:20::42c]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pcnsc-0002Yr-3m for qemu-devel@nongnu.org; Thu, 16 Mar 2023 09:42:55 -0400 Received: by mail-pf1-x42c.google.com with SMTP id s8so1042171pfk.5 for ; Thu, 16 Mar 2023 06:42:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1678974172; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=uNa1IvKBI6YwaZck5BxEV6vCD8ZEYxZqLISguOw2G64=; b=u8HBxecxMBJltHsLlBvqxGFqvcZDuuXXXMjYALI9tFgcFI8UA0aMPYULLLR8Yapowb KCvUuhC04rux1BgYtCJ+LWjKKSVMGmguwFhhNoimg7H04Vvx2ufknD9IsvLf52rZfMRN 5RmJukR2+iRk2u0Ps5HHHqPWBiKpKYxAOWLLp2BsPxAHq6EJSEiwhPP6cOuZSBHnpUr/ ym0R9EmNHlGfFBgRf2w7Vj6kegn7lcXfEJ5IWZz6VLDNUSLxDupLLJ1jwrXnzSx1YyIY 9OInFXLPQS2KYavYiCYpzrj4vIqcbhpRS3bI+1fJ6ou4osTifzMjl7QtWhVPj7sl7/8u nFLA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1678974172; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=uNa1IvKBI6YwaZck5BxEV6vCD8ZEYxZqLISguOw2G64=; b=KAw2k38M+KQZxs2h+rl2AgINrhfe02/xZbUhSOweVW2kyxJJLcyuZ5UrCo2cOp2eew wclsGpD1SiQB/rGvZeaIXZTtAZr6tJHQ8+OHWvnpP4Tz4pf/U5rykJUIG3grWCscJV8F I1lxW0I7gg6FvOCiGkGJ+84mfDSNupypetAyp/3EpyDi1Whp3kyHoHa9Jcm6R9vYA6sJ SHr6LjeRFb0Z2fefVPqvEPvkUEmMS2UkJiot9xqvObePxDzBn3etUN9jnsFNR2Lf09FR YvUAbKibemLKEZwCdn0qDHtS6FtybRgmjKeEGZiPEj4vi/tJKJRvdTTpnMQPMqvlku+e mFTQ== X-Gm-Message-State: AO0yUKVgnFP3RuQ8S7+qmJlQQJAvFuzLcR9THJQvsoDy21xcWGlgj8bo VIhtOJ5M+TuoYXUjUiDFF+MUPEzhvLAxhL8WZEN9gA== X-Google-Smtp-Source: AK7set9Zpu1FBpojaYPRnXj84Dgo7zLpcuBll/NiM35nUns78pTf2gttmN1i4HURYB9kuBjFBcEZH117LqcPHi/nn0A= X-Received: by 2002:a65:5087:0:b0:503:a26a:2e7a with SMTP id r7-20020a655087000000b00503a26a2e7amr904333pgp.6.1678974172412; Thu, 16 Mar 2023 06:42:52 -0700 (PDT) MIME-Version: 1.0 References: <20230314114431.1096972-1-peter.maydell@linaro.org> <8f048b8a-55f0-d124-3cb7-9a34e863149f@vivier.eu> In-Reply-To: <8f048b8a-55f0-d124-3cb7-9a34e863149f@vivier.eu> From: Peter Maydell Date: Thu, 16 Mar 2023 13:42:41 +0000 Message-ID: Subject: Re: [PATCH] docs/sphinx/kerneldoc.py: Honour --enable-werror To: Laurent Vivier Cc: qemu-devel@nongnu.org, =?UTF-8?B?QWxleCBCZW5uw6ll?= , Thomas Huth , "qemu-trivial@nongnu.org" Content-Type: multipart/alternative; boundary="0000000000002255bb05f704a3b3" Received-SPF: pass client-ip=2607:f8b0:4864:20::42c; envelope-from=peter.maydell@linaro.org; helo=mail-pf1-x42c.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org --0000000000002255bb05f704a3b3 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Thu, 16 Mar 2023 at 13:40, Laurent Vivier wrote: > > Le 14/03/2023 =C3=A0 12:44, Peter Maydell a =C3=A9crit : > > Currently, the kerneldoc Sphinx plugin doesn't honour the > > --enable-werror configure option, so its warnings are never fatal. > > This is because although we do pass sphinx-build the -W switch, the > > warnings from kerneldoc are produced by the scripts/kernel-doc script > > directly and don't go through Sphinx's "emit a warning" function. > > > > When --enable-werror is in effect, pass sphinx-build an extra > > argument -Dkerneldoc_werror=3D1. The kerneldoc plugin can then use > > this to determine whether it should be passing the kernel-doc script > > -Werror. > > > > We do this because there is no documented mechanism for > > a Sphinx plugin to determine whether sphinx-build was > > passed -W or not; if one is provided then we can switch to > > that at a later date: > > https://github.com/sphinx-doc/sphinx/issues/11239 > > > > Signed-off-by: Peter Maydell > > --- > > NB: we need to land the fix for the current outstanding > > warning before this one can go in... > > https://lore.kernel.org/qemu-devel/20230310103123.2118519-11-alex.bennee@li= naro.org/ > > --- > > docs/meson.build | 2 +- > > docs/sphinx/kerneldoc.py | 5 +++++ > > 2 files changed, 6 insertions(+), 1 deletion(-) > I've applied it to my trivial-patches branch, > but if you want to apply it via some doc or misc branches, let me know. Trivial is fine, but make sure you've put in the fix for the outstanding warning first :-) -- PMM --0000000000002255bb05f704a3b3 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Thu, 16 Mar 2023 at 13:40, Laurent Vivier <<= a href=3D"mailto:laurent@vivier.eu">laurent@vivier.eu> wrote:
>= ;
> Le 14/03/2023 =C3=A0 12:44, Peter Maydell a =C3=A9crit :
> = > Currently, the kerneldoc Sphinx plugin doesn't honour the
> = > --enable-werror configure option, so its warnings are never fatal.
= > > This is because although we do pass sphinx-build the -W switch, t= he
> > warnings from kerneldoc are produced by the scripts/kernel-= doc script
> > directly and don't go through Sphinx's &quo= t;emit a warning" function.
> >
> > When --enable-we= rror is in effect, pass sphinx-build an extra
> > argument -Dkerne= ldoc_werror=3D1.=C2=A0 The kerneldoc plugin can then use
> > this = to determine whether it should be passing the kernel-doc script
> >= ; -Werror.
> >
> > We do this because there is no documen= ted mechanism for
> > a Sphinx plugin to determine whether sphinx-= build was
> > passed -W or not; if one is provided then we can swi= tch to
> > that at a later date:
> > https://github.com/sphinx-doc/sph= inx/issues/11239
> >
> > Signed-off-by: Peter Maydell= <peter.maydell@linaro.org>
> > ---
> > NB: we need to land the fix for the cu= rrent outstanding
> > warning before this one can go in...
>= > https://lore.kernel.org/qemu-devel/202303101031= 23.2118519-11-alex.bennee@linaro.org/
> > ---
> > =C2= =A0 docs/meson.build =C2=A0 =C2=A0 =C2=A0 =C2=A0 | 2 +-
> > =C2=A0= docs/sphinx/kerneldoc.py | 5 +++++
> > =C2=A0 2 files changed, 6 = insertions(+), 1 deletion(-)

> I've applied it to my trivial-= patches branch,
> but if you want to apply it via some doc or mi= sc branches, let me know.

Trivial is fine, but mak= e sure you've put in the fix for
the outstanding warning firs= t :-)

-- PMM


--0000000000002255bb05f704a3b3--