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

[Mauro Carvalho Chehab]

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

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