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 [off-list ref] wrote:

quoted

Em Wed, 10 Sep 2025 13:51:40 +0300
Jani Nikula [off-list ref] escreveu:

quoted

On Thu, 04 Sep 2025, Mauro Carvalho Chehab [off-list ref] wrote:

quoted

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.

quoted

quoted

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