On Fri, Sep 12, 2025 at 12:22:42PM +0300, Jani Nikula wrote:
> On Fri, 12 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> wrote:
> > Em Wed, 10 Sep 2025 13:51:40 +0300
> > Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu:
> >
> >> On Thu, 04 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
