Re: [PATCH v6 10/21] tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build

On Wed, Sep 17, 2025 at 05:35:31PM +0900, Akira Yokosawa wrote:

[+CC: Jani, -CC: rust people and list]

On Tue, 16 Sep 2025 12:22:46 +0200, Mauro Carvalho Chehab wrote:

quoted

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.

On a side note, there was a line number increase due to the
conversion (ignoring comments) is:

 Documentation/Makefile          |  131 +++----------
 tools/docs/sphinx-build-wrapper |  293 +++++++++++++++++++++++++++++++
 2 files changed, 323 insertions(+), 101 deletions(-)

Comments and descriptions adds:
 tools/docs/sphinx-build-wrapper | 261 +++++++++++++++++++++++++++++++-

So, about half of the script are comments/descriptions.

This is because some things are more verbosed on Python and because
it requires reading env vars from Makefile. Besides it, this script
has some extra features that don't exist at the Makefile:

- It can be called directly from command line;
- It properly return PDF build errors.

When running the script alone, it will only take handle sphinx-build
targets. On other words, it won't runn make rustdoc after building
htmlfiles, nor it will run the extra check scripts.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile          | 131 ++-----
 tools/docs/sphinx-build-wrapper | 581 ++++++++++++++++++++++++++++++++
 2 files changed, 611 insertions(+), 101 deletions(-)
 create mode 100755 tools/docs/sphinx-build-wrapper

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 7570d4cf3b13..4736f02b6c9e 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -23,21 +23,22 @@ SPHINXOPTS    =
 SPHINXDIRS    = .
 DOCS_THEME    =
 DOCS_CSS      =
-_SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))

Wait!  In the cover-letter, you said:

    It should be noticed that it is out of the scope of this series
    to change the implementation. Surely the process can be improved,
    but first let's consolidate and document everything on a single
    place.

Removing current restriction on SPHINXDIRS does look inconsistent with
your own words to me.

You misread the patch. Look better some hunks below:

    +# Used only on help
    +_SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
    +

Patch doesn't remove _SPHINXDIRS. It just moves it to be closer to the
help and document that this is used only there.

So, I guess I have to NAK 06/21 as well.

Regards,
Akira

-- 
Thanks,
Mauro