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:

> 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.
>
> Such script is designed to work both as an standalone command
> and as part of a Makefile. As such, it properly handles POSIX
> jobserver used by GNU make.
>
> It should be noticed that, when running the script alone,
> it will only take care of sphinx-build and cleandocs target.
> As such:
>
> - it won't run "make rustdoc";
> - no extra checks.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .pylintrc                    |   2 +-
>  scripts/sphinx-build-wrapper | 627 +++++++++++++++++++++++++++++++++++
>  2 files changed, 628 insertions(+), 1 deletion(-)
>  create mode 100755 scripts/sphinx-build-wrapper

As a whole I like the idea of this - I would rather be reading code in
Python than in makefilese.  But I have some overall notes...

I am a bit dismayed by the size of it; this is many times the amount of
code it allows us to remove from the makefile.  Perhaps there's nothing
to be done for that, but ...

Is there value in the SphinxBuilder class?  Just because you can create
classes in Python doesn't mean that you have to; I'm not sure why you
would create one here rather than just doing it all at the module level.

Is the "search for a newer Python" code really going to be useful for
anybody?  It seems like a lot of work (and code) to try to quietly patch
things up for somebody who has some sort of a strange setup.

Please, no "except Exception:"  (or the equivalent bare "except:").
That bit of locale tweaking shows up in enough places that it should
maybe go into a little helper module rather than being repeatedly
open-coded?

Thanks,

jon