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

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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <wasa5qgsl2fzltmcqgfapcel42op6waaqoqfwxvbz2jckotrep@rog4gu7mxztz>
Date: Wed, 17 Sep 2025 17:18:13 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Akira Yokosawa <akiyks@...il.com>
Cc: mchehab+huawei@...nel.org, corbet@....net, linux-doc@...r.kernel.org, 
	linux-kernel@...r.kernel.org, Jani Nikula <jani.nikula@...ux.intel.com>
Subject: 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:
> > 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@...nel.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