linux-kernel - Re: [PATCH v4 10/19] tools/docs: sphinx-build-wrapper: add support to run inside venv

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 for Android: free password hash cracker in your pocket

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

Message-ID: <tarfb5x6kg6s3q3yboep6obfvi4s6ahbj2pkcyvgbyvcwrrfxw@v4pnnpjivwwx>
Date: Fri, 12 Sep 2025 14:34:16 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jani Nikula <jani.nikula@...ux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, 
	Jonathan Corbet <corbet@....net>, Linux Doc Mailing List <linux-doc@...r.kernel.org>, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH v4 10/19] tools/docs: sphinx-build-wrapper: add support
 to run inside venv

On Fri, Sep 12, 2025 at 12:22:42PM +0300, Jani Nikula wrote:
> On Fri, 12 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> > Em Wed, 10 Sep 2025 13:51:40 +0300
> > Jani Nikula <jani.nikula@...ux.intel.com> escreveu:
> >
> >> On Thu, 04 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> >> > Sometimes, it is desired to run Sphinx from a virtual environment.
> >> > Add a command line parameter to automatically build Sphinx from
> >> > such environment.  
> >> 
> >> Why?
> >
> > In my case, to be able to test build with different Sphinx versions.
> > On some distros, only venv works.
> 
> I mean why add the complexity of running inside a venv in the wrapper.

I don't think it venv support is complex.

> 
> >> If you want Sphinx from a virtual environment, you enter the
> >> environment, and run the regular build, with sphinx-build from the PATH
> >> that points at the venv.
> >
> > when you do that, ./scripts/spdxcheck.py breaks, affecting checkpatch.
> 
> Then you could turn the whole argument around, and say spdxcheck.py
> should jump through venv and dependency hoops instead of the docs build.

Neither spdxcheck.py nor checkpatch recommends venv; make docs targets do.

> The point is, it should be the user's responsibility to deal with the
> environment and the dependencies.
> 
> If they're setting up a virtual environment, and it affects checkpatch,
> then they should also include the spdxcheck.py dependencies in the
> virtual environment.

They are because we're recommending it.

> This feels like reinventing pipx in a Sphinx wrapper.
> 
> We should *reduce* the complexity, not increase it.

Complexity is not the issue: There are several things a the Kernel
tree that are complex. Here, the entire wrapper script (not counting
blank lines/comments) is not more than ~300 lines of code, splitted
on multiple functions. This is not complex.

The big issue is what we have now where docs makefile is full of
hacks:

    - scripts to workaround issues;
    - "|| exit" to fix broken latexmk/xelatex error outputs;
    - "+" to use GNU make parallelism;
    - complex call macros;
    - ...

None of those documented.

Liking or not, this series as a whole makes a lot clearer what
is done to build preparation, Sphinx build and post-build steps
that are required to produce Kernel docs. Also, almost half of
it is documentation. IMHO, a lot better from what we have so
far.

-- 
Thanks,
Mauro