Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc

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

Em Thu, 14 Aug 2025 07:52:22 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > This series is big (51 patches) because it needs to fix thousands of
> > broken cross references on media. I may end splitting it on two series
> > to make easier for review, one for the script and another for media doc
> > fixes.  
> 
> That might help, yes.
> 
> > Such series affect this RFC as it is creating a tools/docs and placing 
> > there the parse-headers.py code as:
> >
> > 	 tools/docs/lib/parse_data_structs.py                                  |  230 +++++++++++++++--------------------
> > 	 tools/docs/parse-headers.py                                           |    5 
> >
> > Now, if you prefer tools/doc instead and/or place the libs elsewhere,
> > we have a couple of options:
> >
> > 1. rebase my series to do the changes. I suspect that there won't
> >    be much conflicts, but this may delay a little bit sending you
> >    what I have;
> >
> > 2. add a patch at the end moving stuff elsewhere;
> >
> > 3. on your series, move them elsewhere.
> >
> > What do you prefer?  
> 
> Between "tools/doc" and "tools/docs" I don't really have overly strong
> feelings; if you work has the latter we can just stick with that.  If
> you propose "tools/Documentation", though, expect resistance :)

<joke>
Heh, I'm tempted to propose:
	/Documentation -> /docs
or
	/Documentation -> /Docs
</joke>

Ok, so let's keep tools/docs then. We need to decide about python
lib. On my series, I'm placing at tools/docs/lib, but I guess we
can change it later.

From my side, I would prefer to have a single directory for tools,
as we may place there things that aren't specific to docs.

For instance, I have my own class that I use for command execution,
using asyncio. The rationale is that it allows output messages in
real time without needing to wait for the entire process to end(*).

(*) I recently discovered a way to do that without needing asyncio,
    which makes the code a little bit simpler.

Either using asyncio or not, a class for such purpose is something
that multiple tools could use. So, a generic dir like tools/lib, 
lib/python, ... IMO makes sense.

> As I said, my series was an RFC to see what it would look like; it did't
> take all that long the first time around, and will be even quicker to
> redo on top of a new base, whatever that turns out to be.

With regards to the RFC, IMO we still may need to discuss how we'll end 
placing libraries under a LIBDIR. IMO, your RFC should also propose
a directory structure. I mean, we could have something like:

	LIBDIR     # either tools/docs/lib, tools/lib, lib/python or whatever
	|
	+---> common
	\---> docs
		|
	    	+---> kdoc
	    	\---> abi

We could instead do:
	- flatten "common" to LIBDIR; or:
	- flatten "docs" to LIBDIR; or:
	- flatten both but keeping kdoc, abi, ... directories inside
	  LIBDIR; or:
	- have a completely flatten directory with everything
	  under LIBDIR.

 
> Thanks,
> 
> jon



Thanks,
Mauro