linux-kernel - Re: [PATCH 00/13] Add kernel-doc modules to Documentation/tools

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: <20260114212030.28129f38@foz.lan>
Date: Wed, 14 Jan 2026 21:20:30 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, "
 Nícolas F. R. A. Prado" <nfraprado@...labora.com>, Randy
 Dunlap <rdunlap@...radead.org>, Shuah Khan <skhan@...uxfoundation.org>
Subject: Re: [PATCH 00/13] Add kernel-doc modules to Documentation/tools

Em Wed, 14 Jan 2026 11:01:45 -0700
Jonathan Corbet <corbet@....net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:
> 
> > With this version, python files inside tools/ or scripts/
> > can be documented, but there is a catch (probably due to PEP8):
> >
> >     - files must end with ".py"
> >     - file names can't have "-".
> >
> > So, unfortunately, we can't document kernel-doc.py, except if
> > we rename it to kernel_doc.py.  
> 
> That is ... irritating ...

Agreed, but this is not really a problem with Sphinx but with
Python itself: you can't include any module that has "-" on it, or
doesn't end with ".py"[1].

[1] I guess it is actually possible, but only using low-level APIs,
    e.g. using importlib.util, importlib.util.module_from_spec(spec)
    and other dirty tricks, but this is certainly something we should
    avoid to do.

> You've probably seen my other series to finally ... rename
> kernel-doc.py. 

Just saw it ;-)

> We could certainly rename it to something different.
> But I really dislike having language extensions on files meant to be
> executed as commands; you shouldn't care what language it's written in
> when you run it.

I don't like it either, but Python is really picky on some things.

The problem here is that this is a Python policy violation. To change
that, one needs to write a PEP and convince Python maintainers to merge
it, together with changes on python "import" directive.

Alternatively, assuming that some magic words would be enough to
convince importlib to load a name without ".py" and with "-", it could be
easier to convince Sphinx autodoc maintainers to take a patch, as they're 
probably using importlib somewhere to dynamically import a file based 
at the string inside "automodule" directive. On a quick grep,
this seems to be the case, and such logic is inside:

	sphinx/ext/autodoc/importer.py

> In the end, I'd say let's not worry about running autodoc on that file.
> All there is to document is its command line, and we can certainly
> maintain that separately.

It may be true for kernel-doc, but:

- there are other scripts that we may want to document; and:
- we need to define a naming convention for python code

Also,

- keeping it in separate makes harder to maintain.

So, even if we don't actually add kernel-doc docstrings and
functions via autodoc, I think it is still worth having a
name convention that would allow that.

Thanks,
Mauro