From: Jonathan Corbet <corbet@lwn.net>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: "Mauro Carvalho Chehab" <mchehab+huawei@kernel.org>,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
"Nícolas F. R. A. Prado" <nfraprado@collabora.com>,
"Randy Dunlap" <rdunlap@infradead.org>,
"Shuah Khan" <skhan@linuxfoundation.org>
Subject: Re: [PATCH 00/13] Add kernel-doc modules to Documentation/tools
Date: Wed, 14 Jan 2026 11:01:45 -0700 [thread overview]
Message-ID: <874iooul86.fsf@trenco.lwn.net> (raw)
In-Reply-To: <cover.1768396023.git.mchehab+huawei@kernel.org>
Mauro Carvalho Chehab <mchehab+huawei@kernel.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 ...
You've probably seen my other series to finally ... rename
kernel-doc.py. 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.
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.
jon
next prev parent reply other threads:[~2026-01-14 18:01 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-01-14 13:17 [PATCH 00/13] Add kernel-doc modules to Documentation/tools Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 01/13] docs: custom.css: prevent li marker to override text Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 02/13] docs: enable Sphinx autodoc extension to allow documenting python Mauro Carvalho Chehab
2026-01-15 10:19 ` Jani Nikula
2026-01-15 11:50 ` Mauro Carvalho Chehab
2026-01-15 12:18 ` Jani Nikula
2026-01-15 12:57 ` Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 03/13] docs: custom.css: add CSS for python Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 04/13] docs: kdoc: latex_fonts: Improve docstrings and comments Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 05/13] docs: kdoc_files: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 06/13] docs: kdoc_item: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 07/13] docs: kdoc_parser: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 08/13] docs: kdoc_output: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 09/13] docs: kdoc_re: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 10/13] docs: kdoc: parse_data_structs: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 11/13] docs: kdoc: enrich_formatter: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 12/13] docs: kdoc: python_version: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 13/13] docs: add kernel-doc modules documentation Mauro Carvalho Chehab
2026-01-14 18:01 ` Jonathan Corbet [this message]
2026-01-14 20:20 ` [PATCH 00/13] Add kernel-doc modules to Documentation/tools Mauro Carvalho Chehab
2026-01-14 20:46 ` Jonathan Corbet
2026-01-15 1:29 ` Mauro Carvalho Chehab
2026-01-15 10:17 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874iooul86.fsf@trenco.lwn.net \
--to=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab+huawei@kernel.org \
--cc=nfraprado@collabora.com \
--cc=rdunlap@infradead.org \
--cc=skhan@linuxfoundation.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox