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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Sun, 22 Jun 2025 12:44:08 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Em Sat, 21 Jun 2025 13:39:09 -0600
> > Jonathan Corbet <corbet@lwn.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...:)

A tools/docs with all doc-related tool there is certainly appealing.
Yet, I would move all such scripts on a separate patchset.

Thanks,
Mauro