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

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> writes:

> Em Sat, 21 Jun 2025 13:39:09 -0600
> Jonathan Corbet <corbet@xxxxxxx> 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