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

[Jonathan Corbet <corbet@lwn.net>]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

>> 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.

...or just ignore it.  There is a reason that "pip" is called "pip"
rather than "pip.py" - the Python folks don't keep those extensions on
commands either.

> 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

No doubt we could do that.  But is it really worth the trouble?  There
is not much in kernel-doc that needs documenting, especially since you
did the work to move the actual functionality into separate modules. 

> 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.

Instead, I think you're trying to take a functionality meant to describe
APIs and use it to document command-line stuff.  I'm happy to live by
the import rules for stuff that is actually imported; I think it makes
less sense to let them drive the naming of files that are outside of
their intended scope.

jon