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

[Jonathan Corbet <corbet@lwn.net>]

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

> Em Thu, 21 Aug 2025 13:36:24 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.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