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

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: <20250815071829.3d5163fc@foz.lan>
Date: Fri, 15 Aug 2025 07:18:29 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>, Randy Dunlap <rdunlap@...radead.org>
Subject: Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc

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

> Mauro Carvalho Chehab <mchehab+huawei@...nel.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