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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2A8BAC0015E for ; Tue, 15 Aug 2023 18:24:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239047AbjHOSYE (ORCPT ); Tue, 15 Aug 2023 14:24:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49122 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239055AbjHOSXu (ORCPT ); Tue, 15 Aug 2023 14:23:50 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E3BB819AF; Tue, 15 Aug 2023 11:23:49 -0700 (PDT) Received: from localhost (unknown [IPv6:2601:281:8300:73::5f6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id A15F82ED; Tue, 15 Aug 2023 18:23:48 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A15F82ED DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1692123828; bh=/WDM2geFXvPyxkbFTUNOqG5i2x2y+X35CYU2z5xHmqM=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=d6omHjT+TcpM0athcXjpHp2g+IsGhtmvETdogzrMyH2vhTR82BaS69oege5OcKx2O Ko5g37wava/y/+EaEUza+oEanEn/8FAfiMgoMecDuz4NpyL2Ah9Y298J/fNVnWkTxu BIkyxTKgmkHTuTVDyj9UZ7s6fKvQJWCaAjZAjHTgvl0WzTATpomaJrO/MiAE2cbwl1 j8OMYDvrBsW0jn4j1wZVpKGG0NPhsCaqr6WdxOiKlerBuXCwaAMRE8hrb2K7peJCQy jjCcMeCu9q8eUnE6SR14DhlZYpBwQamr/NOyMJV3ceS1bfGOPNNRYfldm6psDkkMo3 7FzoFpb4WSscQ== From: Jonathan Corbet To: Carlos Bilbao , "linux-doc@vger.kernel.org" , Linux Kernel Mailing List Cc: Avadhut Naik , Miguel Ojeda , Akira Yokosawa Subject: Re: [RFC] Proposal to relax warnings of htmldocs In-Reply-To: <85964510-4f88-58d2-2687-f7fa76013cf9@amd.com> References: <85964510-4f88-58d2-2687-f7fa76013cf9@amd.com> Date: Tue, 15 Aug 2023 12:23:47 -0600 Message-ID: <87v8dgtb9o.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Carlos Bilbao writes: > Hello all, > > I would like to discuss a recurring issue that we all have encountered > while running `make htmldocs`. The process often generates an overwhelming > amount of warnings that are not relevant to our work, which makes it harder > to identify and address actual warning messages related to our changes. > > One of the reasons for this is the variation in warnings raised by > different compilers. For instance, the Linux kernel robot employs Sparse, > which recently raised a warning that we (Avadhut in CC, and then me > reviewing his patch) did not catch during our testing [1,2]. > > Particularly annoying -to me personally- are warnings of the form: > > "warning: Function parameter or member 'field' not described in 'struct'" > > that seem to enumerate every single undocumented field within a struct. > > I would like to propose something to alleviate this issue before the list > of warnings keeps piling up. ...other than fixing the actual problems? :) > I suggest for the command `make htmldocs` to > only display, by default, warnings directly related to the changes being > made, unless explicitly requested otherwisee. > > I'm thinking we could do this, for example, by making hmtldocs a two-step > process: First running htmldocs as usual but with warnings disabled, and > then generating docs again but only for the new files (see $git diff > --name-only HEAD), with warnings active but limited to the scope of the > changes made. A normal build should just generate warnings for files that have changed (since the last build). Does that not do what you want? Trying to get Sphinx to do smarter things with partial builds seems like a path to frustration. Since the specific warnings you're talking about are generated by kernel-doc, a better solution would probably just invoke it directly. It wouldn't be that hard to bash out a script to feed a given set of files to kernel-doc and see what it says. As an alternative, of course, we could consider turning off those specific warnings entirely for normal builds. Thanks, jon