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: <87bjo8qvi7.fsf@trenco.lwn.net>
Date: Thu, 21 Aug 2025 14:18:08 -0600
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>, Björn
 Roy Baron <bjorn3_gh@...tonmail.com>, Alex Gaynor <alex.gaynor@...il.com>,
 Alice Ryhl <aliceryhl@...gle.com>, Boqun Feng <boqun.feng@...il.com>, Gary
 Guo <gary@...yguo.net>, 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:

> Em Thu, 21 Aug 2025 13:36:24 -0600
> Jonathan Corbet <corbet@....net> escreveu:
>
>> 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.  
>> 
>> So I am just now looking at the script and seeking to understand it, but
>> one thing has jumped at me that I wanted to toss out there...
>> 
>> > +# Minimal supported Python version needed by Sphinx and its extensions
>> > +MIN_PYTHON_VERSION = parse_version("3.7")
>> > +
>> > +# Default value for --venv parameter
>> > +VENV_DEFAULT = "sphinx_latest"
>> > +
>> > +# List of make targets and its corresponding builder and output directory
>> > +TARGETS = {  
>> 
>> We don't at this point have a formal coding standard for Python code,
>> but I do think that we should, to the extent possible, stick to the
>> rules that have been established for C code.  One thing I would really
>> like to see is in the comment style; our rules want:
>> 
>>     /*
>>      * ...C comments spread out with the markers on separate lines
>>      * like this...
>>      */
>> 
>> so can we do something similar for Python?
>> 
>>     #
>>     # Markers above and below
>>     #
>> 
>> I will confess that this matches my personal subject preference, but it
>> also brings us closer to what our C code looks like.
>
> Fine for me. Can I do such changes on a patch at the end of the series
> to prevent rebase conflicts?

Yes, of course - and I don't think we have to fix everything right away
either.  We already have plenty of inconsistent stuff, we can deal with
it in the usual manner, cleaning it up when we're in the neighborhood
anyway.

Thanks,

jon