linux-kernel - Re: [PATCH 0/6] Some improvements for the doc build system

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 for Android: free password hash cracker in your pocket

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

Message-ID: <874iw7boqv.fsf@trenco.lwn.net>
Date: Sun, 22 Jun 2025 12:44:08 -0600
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH 0/6] Some improvements for the doc build system

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> Em Sat, 21 Jun 2025 13:39:09 -0600
> Jonathan Corbet <corbet@....net> escreveu:
>
>> OK, I've applied it, but ... someday, I think the test_doc_build tool
>> should be properly documented and put somewhere under tools/testing.
>
> I added a better documentation for the tool at the v2.
>
> With regards to move to tools, I'm not certain about it as I can see
> advantages and disadvantages. 
>
> Creating a new directory to have just one tool on it seems overkill
> to me. Also, it is easier to type "scripts/..." than 
> "tools/testing/build/..." :-)
>
> There is another aspect: while doing conf.py and Documentation/Makefile
> cleanup, I noticed that there are still lots of hacks inside them,
> that are there from the early days when we adopted Sphinx. Perhaps
> it could make sense to move part of the logic there to this new
> build tool, which could, for instance, replace the logic inside
> scripts/sphinx-pre-install and get rid of some magic at the Makefile
> like the one which handles SPHINXDIRS.
>
> So, at least for now, I would prefer to keep it under scripts.

I pretty strongly disagree ... scripts/ is a dumping ground, nobody
really knows what all that stuff there is, nobody is responsible for it.
Something under tools/ would be more evident as to its purpose and
maintainership.  We could maybe just do tools/docs/ and move things like
sphinx-pre-install there as well...

Anyway, I won't try to hold up this work based on that, but now you know
how I feel...:)

jon