linux-kernel - Re: [PATCH 04/11] scripts: sphinx-build-wrapper: add a wrapper for sphinx-build

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87plco5tb9.fsf@trenco.lwn.net>
Date: Thu, 21 Aug 2025 14:11:06 -0600
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Linux Doc Mailing
 List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Björn Roy Baron
 <bjorn3_gh@...tonmail.com>, Mauro Carvalho Chehab
 <mchehab+huawei@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, Alice
 Ryhl <aliceryhl@...gle.com>, Andreas Hindborg <mchehab+huawei@...nel.org>,
 Benno Lossin <mchehab+huawei@...nel.org>, Boqun Feng
 <boqun.feng@...il.com>, Danilo Krummrich <mchehab+huawei@...nel.org>, Gary
 Guo <gary@...yguo.net>, Miguel Ojeda <mchehab+huawei@...nel.org>, Trevor
 Gross <tmgross@...ch.edu>, linux-kernel@...r.kernel.org,
 rust-for-linux@...r.kernel.org
Subject: Re: [PATCH 04/11] scripts: sphinx-build-wrapper: add a wrapper for
 sphinx-build

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> There are too much magic inside docs Makefile to properly run
> sphinx-build. Create an ancillary script that contains all
> kernel-related sphinx-build call logic currently at Makefile.
>
> Such script is designed to work both as an standalone command
> and as part of a Makefile. As such, it properly handles POSIX
> jobserver used by GNU make.
>
> It should be noticed that, when running the script alone,
> it will only take care of sphinx-build and cleandocs target.
> As such:
>
> - it won't run "make rustdoc";
> - no extra checks.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
>  .pylintrc                    |   2 +-
>  scripts/sphinx-build-wrapper | 627 +++++++++++++++++++++++++++++++++++
>  2 files changed, 628 insertions(+), 1 deletion(-)
>  create mode 100755 scripts/sphinx-build-wrapper

As a whole I like the idea of this - I would rather be reading code in
Python than in makefilese.  But I have some overall notes...

I am a bit dismayed by the size of it; this is many times the amount of
code it allows us to remove from the makefile.  Perhaps there's nothing
to be done for that, but ...

Is there value in the SphinxBuilder class?  Just because you can create
classes in Python doesn't mean that you have to; I'm not sure why you
would create one here rather than just doing it all at the module level.

Is the "search for a newer Python" code really going to be useful for
anybody?  It seems like a lot of work (and code) to try to quietly patch
things up for somebody who has some sort of a strange setup.

Please, no "except Exception:"  (or the equivalent bare "except:").
That bit of locale tweaking shows up in enough places that it should
maybe go into a little helper module rather than being repeatedly
open-coded?

Thanks,

jon