* [PATCH] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-19 6:58 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc
Cc: lrcu, linux-kernel, workflows, linux-sound, rcu, linux-media,
Manuel Ebner
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj() and family")
ptr = kmalloc(sizeof(*ptr), gfp);
-> ptr = kmalloc_obj(*ptr, gfp);
ptr = kmalloc(sizeof(struct some_obj_name), gfp);
-> ptr = kmalloc_obj(*ptr, gfp);
ptr = kzalloc(sizeof(*ptr), gfp);
-> ptr = kzalloc_obj(*ptr, gfp);
ptr = kmalloc_array(count, sizeof(*ptr), gfp);
-> ptr = kmalloc_objs(*ptr, count, gfp);
ptr = kcalloc(count, sizeof(*ptr), gfp);
-> ptr = kzalloc_objs(*ptr, count, gfp);
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
.../RCU/Design/Requirements/Requirements.rst | 6 +++---
Documentation/RCU/listRCU.rst | 2 +-
Documentation/RCU/whatisRCU.rst | 4 ++--
Documentation/core-api/kref.rst | 4 ++--
Documentation/core-api/list.rst | 4 ++--
Documentation/core-api/memory-allocation.rst | 4 ++--
Documentation/driver-api/mailbox.rst | 4 ++--
Documentation/driver-api/media/v4l2-fh.rst | 2 +-
Documentation/kernel-hacking/locking.rst | 4 ++--
Documentation/locking/locktypes.rst | 4 ++--
Documentation/process/coding-style.rst | 8 ++++----
.../sound/kernel-api/writing-an-alsa-driver.rst | 12 ++++++------
Documentation/spi/spi-summary.rst | 4 ++--
.../translations/it_IT/kernel-hacking/locking.rst | 4 ++--
.../translations/it_IT/locking/locktypes.rst | 4 ++--
.../translations/it_IT/process/coding-style.rst | 2 +-
.../translations/sp_SP/process/coding-style.rst | 2 +-
Documentation/translations/zh_CN/core-api/kref.rst | 4 ++--
.../translations/zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/video4linux/v4l2-framework.txt | 2 +-
.../translations/zh_TW/process/coding-style.rst | 2 +-
21 files changed, 42 insertions(+), 42 deletions(-)
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index b5cdbba3ec2e..faca5a9c8c12 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -206,7 +206,7 @@ non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields.
1 bool add_gp_buggy(int a, int b)
2 {
- 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 3 p = kmalloc_obj(*p, GFP_KERNEL);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
@@ -228,7 +228,7 @@ their rights to reorder this code as follows:
1 bool add_gp_buggy_optimized(int a, int b)
2 {
- 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 3 p = kmalloc_obj(*p, GFP_KERNEL);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
@@ -264,7 +264,7 @@ shows an example of insertion:
1 bool add_gp(int a, int b)
2 {
- 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 3 p = kmalloc_obj(*p, GFP_KERNEL);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index d8bb98623c12..48c7272a4ccc 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -276,7 +276,7 @@ The RCU version of audit_upd_rule() is as follows::
list_for_each_entry(e, list, list) {
if (!audit_compare_rule(rule, &e->rule)) {
- ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
+ ne = kmalloc_obj(*entry, GFP_ATOMIC);
if (ne == NULL)
return -ENOMEM;
audit_copy_rule(&ne->rule, &e->rule);
diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index a1582bd653d1..770aab8ea36a 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst
@@ -468,7 +468,7 @@ uses of RCU may be found in listRCU.rst and NMI-RCU.rst.
struct foo *new_fp;
struct foo *old_fp;
- new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
+ new_fp = kmalloc_obj(*new_fp, GFP_KERNEL);
spin_lock(&foo_mutex);
old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
*new_fp = *old_fp;
@@ -570,7 +570,7 @@ The foo_update_a() function might then be written as follows::
struct foo *new_fp;
struct foo *old_fp;
- new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
+ new_fp = kmalloc_obj(*new_fp, GFP_KERNEL);
spin_lock(&foo_mutex);
old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
*new_fp = *old_fp;
diff --git a/Documentation/core-api/kref.rst b/Documentation/core-api/kref.rst
index 8db9ff03d952..1c14c036699d 100644
--- a/Documentation/core-api/kref.rst
+++ b/Documentation/core-api/kref.rst
@@ -40,7 +40,7 @@ kref_init as so::
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -100,7 +100,7 @@ thread to process::
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/core-api/list.rst b/Documentation/core-api/list.rst
index 241464ca0549..86cd0a1b77ea 100644
--- a/Documentation/core-api/list.rst
+++ b/Documentation/core-api/list.rst
@@ -112,7 +112,7 @@ list:
/* State 1 */
- grock = kzalloc(sizeof(*grock), GFP_KERNEL);
+ grock = kzalloc_obj(*grock, GFP_KERNEL);
if (!grock)
return -ENOMEM;
grock->name = "Grock";
@@ -123,7 +123,7 @@ list:
/* State 2 */
- dimitri = kzalloc(sizeof(*dimitri), GFP_KERNEL);
+ dimitri = kzalloc_obj(*dimitri, GFP_KERNEL);
if (!dimitri)
return -ENOMEM;
dimitri->name = "Dimitri";
diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 0f19dd524323..8379775f17d3 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -135,7 +135,7 @@ Selecting memory allocator
The most straightforward way to allocate memory is to use a function
from the kmalloc() family. And, to be on the safe side it's best to use
routines that set memory to zero, like kzalloc(). If you need to
-allocate memory for an array, there are kmalloc_array() and kcalloc()
+allocate memory for an array, there are kmalloc_objs() and kzalloc_objs()
helpers. The helpers struct_size(), array_size() and array3_size() can
be used to safely calculate object sizes without overflowing.
@@ -151,7 +151,7 @@ sizes, the alignment is guaranteed to be at least the largest power-of-two
divisor of the size.
Chunks allocated with kmalloc() can be resized with krealloc(). Similarly
-to kmalloc_array(): a helper for resizing arrays is provided in the form of
+to kmalloc_objs(): a helper for resizing arrays is provided in the form of
krealloc_array().
For large allocations you can use vmalloc() and vzalloc(), or directly
diff --git a/Documentation/driver-api/mailbox.rst b/Documentation/driver-api/mailbox.rst
index 463dd032b96c..4bcd73a99115 100644
--- a/Documentation/driver-api/mailbox.rst
+++ b/Documentation/driver-api/mailbox.rst
@@ -87,8 +87,8 @@ a message and a callback function to the API and return immediately).
struct async_pkt ap;
struct sync_pkt sp;
- dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
- dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
+ dc_sync = kzalloc_obj(*dc_sync, GFP_KERNEL);
+ dc_async = kzalloc_obj(*dc_async, GFP_KERNEL);
/* Populate non-blocking mode client */
dc_async->cl.dev = &pdev->dev;
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index a934caa483a4..38319130ebf5 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -42,7 +42,7 @@ Example:
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh, GFP_KERNEL);
...
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index dff0646a717b..d02e62367c4f 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -442,7 +442,7 @@ to protect the cache and all the objects within it. Here's the code::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -517,7 +517,7 @@ which are taken away, and the ``+`` are lines which are added.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
index 37b6a5670c2f..ac1ad722a9e7 100644
--- a/Documentation/locking/locktypes.rst
+++ b/Documentation/locking/locktypes.rst
@@ -498,7 +498,7 @@ allocating memory. Thus, on a non-PREEMPT_RT kernel the following code
works perfectly::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
But this code fails on PREEMPT_RT kernels because the memory allocator is
fully preemptible and therefore cannot be invoked from truly atomic
@@ -507,7 +507,7 @@ while holding normal non-raw spinlocks because they do not disable
preemption on PREEMPT_RT kernels::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 35b381230f6e..a3bf75dc7c88 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -936,7 +936,7 @@ used.
---------------------
The kernel provides the following general purpose memory allocators:
-kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
+kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
about them. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`
@@ -945,7 +945,7 @@ The preferred form for passing a size of a struct is the following:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
The alternative form where struct name is spelled out hurts readability and
introduces an opportunity for a bug when the pointer variable type is changed
@@ -959,13 +959,13 @@ The preferred form for allocating an array is the following:
.. code-block:: c
- p = kmalloc_array(n, sizeof(...), ...);
+ p = kmalloc_objs(*ptr, n, ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
- p = kcalloc(n, sizeof(...), ...);
+ p = kzalloc_objs(*ptr, n, ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 895752cbcedd..12433612aa9c 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -266,7 +266,7 @@ to details explained in the following section.
....
/* allocate a chip-specific data with zero filled */
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
if (chip == NULL)
return -ENOMEM;
@@ -628,7 +628,7 @@ After allocating a card instance via :c:func:`snd_card_new()`
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
.....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
The chip record should have the field to hold the card pointer at least,
@@ -747,7 +747,7 @@ destructor and PCI entries. Example code is shown first, below::
return -ENXIO;
}
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
if (chip == NULL) {
pci_disable_device(pci);
return -ENOMEM;
@@ -1737,7 +1737,7 @@ callback::
{
struct my_pcm_data *data;
....
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
substream->runtime->private_data = data;
....
}
@@ -3301,7 +3301,7 @@ You can then pass any pointer value to the ``private_data``. If you
assign private data, you should define a destructor, too. The
destructor function is set in the ``private_free`` field::
- struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
+ struct mydata *p = kmalloc_obj(*p, GFP_KERNEL);
hw->private_data = p;
hw->private_free = mydata_free;
@@ -3833,7 +3833,7 @@ chip data individually::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
....
card->private_data = chip;
....
diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst
index 6e21e6f86912..7ad6af76c247 100644
--- a/Documentation/spi/spi-summary.rst
+++ b/Documentation/spi/spi-summary.rst
@@ -249,7 +249,7 @@ And SOC-specific utility code might look something like::
{
struct mysoc_spi_data *pdata2;
- pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
+ pdata2 = kmalloc_obj(*pdata2, GFP_KERNEL);
*pdata2 = pdata;
...
if (n == 2) {
@@ -373,7 +373,7 @@ a bus (appearing under /sys/class/spi_master).
return -ENODEV;
/* get memory for driver's per-chip state */
- chip = kzalloc(sizeof *chip, GFP_KERNEL);
+ chip = kzalloc(*chip, GFP_KERNEL);
if (!chip)
return -ENOMEM;
spi_set_drvdata(spi, chip);
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 4c21cf60f775..acca89a3743a 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -462,7 +462,7 @@ e tutti gli oggetti che contiene. Ecco il codice::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -537,7 +537,7 @@ sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/translations/it_IT/locking/locktypes.rst b/Documentation/translations/it_IT/locking/locktypes.rst
index 1c7056283b9d..d5fa36aa05cc 100644
--- a/Documentation/translations/it_IT/locking/locktypes.rst
+++ b/Documentation/translations/it_IT/locking/locktypes.rst
@@ -488,7 +488,7 @@ o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di
memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di
memoria può essere oggetto di prelazione e quindi non può essere chiamato in un
@@ -497,7 +497,7 @@ trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel
PREEMPT_RT::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index c0dc786b8474..2a499412a2e3 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -943,7 +943,7 @@ Il modo preferito per passare la dimensione di una struttura è il seguente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa, dove il nome della struttura viene scritto interamente,
peggiora la leggibilità e introduce possibili bachi quando il tipo di
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 7d63aa8426e6..44c93d5f6beb 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -955,7 +955,7 @@ La forma preferida para pasar el tamaño de una estructura es la siguiente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa donde se deletrea el nombre de la estructura perjudica
la legibilidad, y presenta una oportunidad para un error cuando se cambia
diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
index b9902af310c5..fcff01e99852 100644
--- a/Documentation/translations/zh_CN/core-api/kref.rst
+++ b/Documentation/translations/zh_CN/core-api/kref.rst
@@ -52,7 +52,7 @@ kref可以出现在数据结构体中的任何地方。
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -106,7 +106,7 @@ Kref规则
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 5a342a024c01..55d5da974d89 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -813,7 +813,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能
会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof
diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
index f0be21a60a0f..ba43c5c4797c 100644
--- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -799,7 +799,7 @@ int my_open(struct file *file)
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh, GFP_KERNEL);
...
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index e2ba97b3d8bb..63c78982a1af 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -827,7 +827,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能
會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof
--
2.53.0
^ permalink raw reply related
* Re: [PATCH v2 00/11] Auto-generate maintainer profile entries
From: Randy Dunlap @ 2026-04-19 0:05 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Albert Ou, Jonathan Corbet,
Mauro Carvalho Chehab, Palmer Dabbelt, Paul Walmsley
Cc: linux-doc, linux-kernel, linux-riscv, workflows, Alexandre Ghiti,
Shuah Khan, Dan Williams
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> Hi Jon,
>
> This patch series change the way maintainer entry profile links
> are added to the documentation. Instead of having an entry for
> each of them at an ReST file, get them from MAINTAINERS content.
>
> That should likely make easier to maintain, as there will be a single
> point to place all such profiles.
>
> The output is a per-subsystem sorted (*) series of links shown as a
> list like this:
>
> - Arm And Arm64 Soc Sub-Architectures (Common Parts)
> - Arm/Samsung S3C, S5P And Exynos Arm Architectures
> - Arm/Tesla Fsd Soc Support
> ...
> - Xfs Filesystem
>
> Please notice that the series is doing one logical change per patch.
> I could have merged some changes altogether, but I opted doing it
> in small steps to help reviews. If you prefer, feel free to merge
> maintainers_include changes on merge.
>
> There is one interesting side effect of this series: there is no
> need to add rst files containing profiles inside a TOC tree: Just
> creating the file anywhere inside Documentation and adding a P entry
> is enough. Adding them to a TOC won't hurt.
>
> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Suggested-by: Dan Williams <djbw@kernel.org>
> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
>
> (*) At the end, I opted to use sorted(), just to ensure it, even
> knowing that MAINTAINER entries are supposed to be sorted, as
> the cost of sorting ~20 already-sorted entries is negligible.
>
> ---
>
> v2:
> - I placed the to MAINTAINERS changes at the beginning.
> - fix a bug when O=DOCS is used;
> - proper handle glob "P" entries (just in case, no profiles use it ATM);
> - when SPHINXDIRS=process, instead of producing warnings, point to
> entries at https://docs.kernel.org;
> - MAINTAINERS parsing now happens just once;
> - The output won't be numered for entries inside numered TOC trees;
> - TOC tree is now hidden;
> - instead of display a TOC tree, it shows a list of profiles,
> ordered and named after file system name taken from MAINTAINERS file;
> - At the output list, both https and file profiles are shown the same
> way.
>
> Mauro Carvalho Chehab (11):
> MAINTAINERS: add an entry for media maintainers profile
> MAINTAINERS: add maintainer-tip.rst to X86
> docs: maintainers_include: auto-generate maintainer profile TOC
> docs: auto-generate maintainer entry profile links
> docs: maintainers_include: use a better title for profiles
> docs: maintainers_include: add external profile URLs
> docs: maintainers_include: preserve names for files under process/
> docs: maintainers_include: Only show main entry for profiles
> docs: maintainers_include: improve its output
> docs: maintainers_include: fix support for O=dir
> docs: maintainers_include: parse MAINTAINERS just once
>
> .../maintainer/maintainer-entry-profile.rst | 24 +--
> .../process/maintainer-handbooks.rst | 17 +-
> Documentation/sphinx/maintainers_include.py | 161 +++++++++++++++---
> MAINTAINERS | 2 +
> 4 files changed, 150 insertions(+), 54 deletions(-)
>
Just a note, not asking for a change or fix:
AFAICT, all P: entries are now listed nicely except for:
P: rust/pin-init/CONTRIBUTING.md
so for the series:
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
thanks.
--
~Randy
^ permalink raw reply
* Re: [PATCH v2 01/11] MAINTAINERS: add an entry for media maintainers profile
From: Randy Dunlap @ 2026-04-19 0:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List
Cc: linux-kernel, linux-riscv, workflows, Dan Williams,
Mauro Carvalho Chehab
In-Reply-To: <361c00348573e45b4e06b674b2b45e47dc65c938.1776405189.git.mchehab+huawei@kernel.org>
On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> The media subsystem has a maintainers entry profile, but its entry
> is missing at MAINTAINERS.
>
> Add it.
>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
> ---
> MAINTAINERS | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index f0b106a4dd96..620219e48f98 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -16115,6 +16115,7 @@ S: Maintained
> W: https://linuxtv.org
> Q: http://patchwork.kernel.org/project/linux-media/list/
> T: git git://linuxtv.org/media.git
> +P: Documentation/driver-api/media/maintainer-entry-profile.rst
> F: Documentation/admin-guide/media/
> F: Documentation/devicetree/bindings/media/
> F: Documentation/driver-api/media/
I now see 2 P: entries for MEDIA INPUT INFRASTRUCTURE
and 2 P: entries for X86 ARCHITECTURE.
(don't know how/why)
--
~Randy
^ permalink raw reply
* [PATCH] docs: kselftest: Document the FORCE_TARGETS build variable
From: Ricardo B. Marlière @ 2026-04-17 17:36 UTC (permalink / raw)
To: Shuah Khan, Jonathan Corbet
Cc: Shuah Khan, linux-kselftest, workflows, linux-doc, linux-kernel,
Ricardo B. Marlière
FORCE_TARGETS has been part of the kselftest build system for
some time but is absent from the developer documentation. Without
an entry here, users relying on kselftest in CI pipelines would
have to read the selftests Makefile directly to discover the
option.
A build that exits zero despite some targets failing can mask
real breakage and mislead automated systems into reporting
success. Add a dedicated section so that CI authors can easily
find and adopt FORCE_TARGETS=1 to turn such silent partial
failures into hard errors.
Signed-off-by: Ricardo B. Marlière <rbm@suse.com>
---
Documentation/dev-tools/kselftest.rst | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
index 18c2da67fae4..d7bfe320338c 100644
--- a/Documentation/dev-tools/kselftest.rst
+++ b/Documentation/dev-tools/kselftest.rst
@@ -126,6 +126,18 @@ dedicated skiplist::
See the top-level tools/testing/selftests/Makefile for the list of all
possible targets.
+Requiring all targets to build successfully
+===========================================
+
+By default, the build succeeds as long as at least one target builds
+without error. Set ``FORCE_TARGETS=1`` to instead require every target to
+build successfully; make will abort as soon as any target fails::
+
+ $ make -C tools/testing/selftests FORCE_TARGETS=1
+
+This applies to both the ``all`` and ``install`` targets and is useful in
+CI environments where a silent partial build would be misleading.
+
Running the full range hotplug selftests
========================================
---
base-commit: 83ef26f911432d9c98b6d8b6ed0709a8b79cd834
change-id: 20260417-selftests-docs-fdf4e922ad20
Best regards,
--
Ricardo B. Marlière <rbm@suse.com>
^ permalink raw reply related
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-17 6:18 UTC (permalink / raw)
To: Randy Dunlap
Cc: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley, linux-doc, linux-kernel, linux-riscv, workflows,
Alexandre Ghiti, Shuah Khan, Dan Williams
In-Reply-To: <c325d85e-98d2-4e35-b7e7-7bb4d6ee77aa@infradead.org>
On Thu, 16 Apr 2026 14:32:04 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
> On 4/16/26 1:00 AM, Mauro Carvalho Chehab wrote:
> > On Wed, 15 Apr 2026 13:41:16 -0700
> > Randy Dunlap <rdunlap@infradead.org> wrote:
> >
> >> Hi Mauro,
> >>
> >> Thanks for tackling this issue.
> >>
> >> On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
> >>> Date: Tue, 14 Apr 2026 16:29:03 +0200
> >>> From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >>> To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
> >>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
> >>> Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
> >>>
> >>> Hi Dan/Jon,
> >>>
> >>> This patch series change the way maintainer entry profile links
> >>> are added to the documentation. Instead of having an entry for
> >>> each of them at an ReST file, get them from MAINTAINERS content.
> >>>
> >>> That should likely make easier to maintain, as there will be a single
> >>> point to place all such profiles.
> >>>
> >>> On this version, I added Dan's text to patch 4.
> >>>
> >>> I also added a couple of other patches to improve its output. While
> >>> I could have them merged at the first patch, I opted to make them
> >>> separate, as, in case of problems or needed changes, it would be
> >>> easier to revert or modify the corresponding logic. Also, it should
> >>> be better to review, in case one wants some changes there.
> >>>
> >>> The main changes against RFC are:
> >>>
> >>> - now, the TOC will be presented with 1 depth identation level,
> >>> meaning that it would look like a list;
> >>> - for files outside Documentation/process, it will use the name of
> >>> the subsystem with title capitalization for the name of the
> >>> profile entry;
> >>> - the logic also parses and produces a list of profiles that are
> >>> maintained elsewhere, picking its http/https link;
> >>> - entries are now better sorted: first by subsystem name, then
> >>> by its name.
> >>>
> >>> Suggested-by: Dan Williams <djbw@kernel.org>
> >>> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
> >>>
> >>> Mauro Carvalho Chehab (8):
> >>> docs: maintainers_include: auto-generate maintainer profile TOC
> >>> MAINTAINERS: add an entry for media maintainers profile
> >>> MAINTAINERS: add maintainer-tip.rst to X86
> >>> docs: auto-generate maintainer entry profile links
> >>> docs: maintainers_include: use a better title for profiles
> >>> docs: maintainers_include: add external profile URLs
> >>> docs: maintainers_include: preserve names for files under process/
> >>> docs: maintainers_include: Only show main entry for profiles
> >>>
> >>> .../maintainer/maintainer-entry-profile.rst | 24 +---
> >>> .../process/maintainer-handbooks.rst | 17 ++-
> >>> Documentation/sphinx/maintainers_include.py | 131 +++++++++++++++---
> >>> MAINTAINERS | 2 +
> >>> 4 files changed, 128 insertions(+), 46 deletions(-)
> >>
> >> When building htmldocs with O=DOCS, I get a bunch of warnings.
> >> I tested against today's linux-next tree.
> >>
> >> The 'make O=DOCS htmldocs' warnings are (subset of all warnings):
> >>
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]
> >>
> >> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >>
> >> linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
> >> linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> >> linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> >> linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
> >> linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
> >
> > Heh, os.path.relpath() does the wrong thing here.
> >
> > The enclosed patch should handle it better.
> >
> > Thanks,
> > Mauro
> >
> > [PATCH] docs: maintainers_include: fix support for O=dir
> >
> > os.path.relpath() will do the wrong thing with O=dir, as the build
> > system uses "cd <dir>" internally.
> >
> > Solve it by using app.srcdir, which, on normal cases, point to
> > Documentation/, or, when SPHINXDIRS=process, it will be set with
> > Documentation/process.
> >
> > While here, remove a dead code while writing maintainer profiles,
> > as now all entries should have both profile and entry.
> >
> > Reported-by: Randy Dunlap <rdunlap@infradead.org>
> > Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >
> > diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> > index 5413c1350bba..fff9bdd55a56 100755
> > --- a/Documentation/sphinx/maintainers_include.py
> > +++ b/Documentation/sphinx/maintainers_include.py
> > @@ -27,15 +27,24 @@ from docutils import statemachine
> > from docutils.parsers.rst import Directive
> > from docutils.parsers.rst.directives.misc import Include
> >
> > +#
> > +# Base URL for intersphinx-like links to maintainer profiles
> > +#
> > +KERNELDOC_URL = "https://docs.kernel.org/"
> > +
> > def ErrorString(exc): # Shamelessly stolen from docutils
> > return f'{exc.__class__.__name}: {exc}'
> >
> > __version__ = '1.0'
> >
> > +base_dir = "."
> > +
> > class MaintainersParser:
> > """Parse MAINTAINERS file(s) content"""
> >
> > - def __init__(self, base_path, path):
> > + def __init__(self, path):
> > + global base_dir
> > +
> > self.profile_toc = set()
> > self.profile_entries = {}
> >
> > @@ -76,9 +85,18 @@ class MaintainersParser:
> > #
> > # Handle profile entries - either as files or as https refs
> > #
> > - match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
> > + match = re.match(r"P:\s*Documentation(/\S+)\.rst", line)
> > if match:
> > - entry = os.path.relpath(match.group(1), base_path)
> > + entry = os.path.relpath(match.group(1), base_dir)
> > +
> > + #
> > + # When SPHINXDIRS is used, it will try to reference files
> > + # outside srctree, causing warnings. To avoid that, point
> > + # to the latest official documentation
> > + #
> > + if entry.startswith("../"):
> > + entry = KERNELDOC_URL + match.group(1) + ".html"
> > +
> > if "*" in entry:
> > for e in glob(entry):
> > self.profile_toc.add(e)
> > @@ -189,10 +207,10 @@ class MaintainersInclude(Include):
> > """MaintainersInclude (``maintainers-include``) directive"""
> > required_arguments = 0
> >
> > - def emit(self, base_path, path):
> > + def emit(self, path):
> > """Parse all the MAINTAINERS lines into ReST for human-readability"""
> >
> > - output = MaintainersParser(base_path, path).output
> > + output = MaintainersParser(path).output
> >
> > # For debugging the pre-rendered results...
> > #print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
> > @@ -213,11 +231,10 @@ class MaintainersInclude(Include):
> >
> > # Append "MAINTAINERS"
> > path = os.path.join(path, "MAINTAINERS")
> > - base_path = os.path.dirname(self.state.document.document.current_source)
> >
> > try:
> > self.state.document.settings.record_dependencies.add(path)
> > - lines = self.emit(base_path, path)
> > + lines = self.emit(path)
> > except IOError as error:
> > raise self.severe('Problems with "%s" directive path:\n%s.' %
> > (self.name, ErrorString(error)))
> > @@ -227,27 +244,20 @@ class MaintainersInclude(Include):
> > class MaintainersProfile(Include):
> > required_arguments = 0
> >
> > - def emit(self, base_path, path):
> > + def emit(self, path):
> > """Parse all the MAINTAINERS lines looking for profile entries"""
> >
> > - maint = MaintainersParser(base_path, path)
> > + maint = MaintainersParser(path)
> >
> > #
> > # Produce a list with all maintainer profiles, sorted by subsystem name
> > #
> > output = ""
> > -
> > - for profile, entry in maint.profile_entries.items():
> > + for profile, entry in sorted(maint.profile_entries.items()):
> > if entry.startswith("http"):
> > - if profile:
> > - output += f"- `{profile} <{entry}>`_\n"
> > - else:
> > - output += f"- `<{entry}>_`\n"
> > + output += f"- `{profile} <{entry}>`_\n"
> > else:
> > - if profile:
> > - output += f"- :doc:`{profile} <{entry}>`\n"
> > - else:
> > - output += f"- :doc:`<{entry}>`\n"
> > + output += f"- :doc:`{profile} <{entry}>`\n"
> >
> > #
> > # Create a hidden TOC table with all profiles. That allows adding
> > @@ -277,11 +287,10 @@ class MaintainersProfile(Include):
> >
> > # Append "MAINTAINERS"
> > path = os.path.join(path, "MAINTAINERS")
> > - base_path = os.path.dirname(self.state.document.document.current_source)
> >
> > try:
> > self.state.document.settings.record_dependencies.add(path)
> > - lines = self.emit(base_path, path)
> > + lines = self.emit(path)
> > except IOError as error:
> > raise self.severe('Problems with "%s" directive path:\n%s.' %
> > (self.name, ErrorString(error)))
> > @@ -289,6 +298,15 @@ class MaintainersProfile(Include):
> > return []
> >
> > def setup(app):
> > + global base_dir
> > +
> > + #
> > + # partition will pick the path after Documentation.
> > + # NOTE: we're using os.fspath() here because of a Sphinx warning:
> > + # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
> > + #
> > + _, _, base_dir = os.fspath(app.srcdir).partition("Documentation")
> > +
> > app.add_directive("maintainers-include", MaintainersInclude)
> > app.add_directive("maintainers-profile-toc", MaintainersProfile)
> > return dict(
>
> With that patch I still see 6 warnings:
>
> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
Heh, dealing with patches is tricky. At least on my tests, things seem
to be working fine at v2 of this series:
https://lore.kernel.org/linux-doc/cover.1776405189.git.mchehab+huawei@kernel.org/T/#t
here, I tested building docs with and without SPHINXDIRS=process and
O=DOCS, but it is nice if you can re-test it.
Basically, when SPHINXDIRS=process is used, instead of generating
wakings for docs outside process/ directory, it converts them to
hyperlinks to their corresponding name inside
https://docs.kernel.org/ (*).
(*) The logic assumes that the file would exist there, but doesn't
check.
Thanks,
Mauro
^ permalink raw reply
* [PATCH v2 10/11] docs: maintainers_include: fix support for O=dir
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
os.path.relpath() will do the wrong thing with O=dir, as the build
system uses "cd <dir>" internally.
Solve it by using app.srcdir, which, on normal cases, point to
Documentation/, or, when SPHINXDIRS=process, it will be set with
Documentation/process.
While here, remove a dead code while writing maintainer profiles,
as now all entries should have both profile and entry.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 71 +++++++++++++++------
1 file changed, 50 insertions(+), 21 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 5413c1350bba..ae52e8198750 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -27,15 +27,24 @@ from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
+#
+# Base URL for intersphinx-like links to maintainer profiles
+#
+KERNELDOC_URL = "https://docs.kernel.org/"
+
def ErrorString(exc): # Shamelessly stolen from docutils
return f'{exc.__class__.__name}: {exc}'
__version__ = '1.0'
+app_dir = "."
+
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, base_path, path):
+ def __init__(self, path):
+ global app_dir
+
self.profile_toc = set()
self.profile_entries = {}
@@ -57,6 +66,9 @@ class MaintainersParser:
field_content = ""
subsystem_name = None
+ base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
+ print("BASE DIR", base_dir)
+
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
if descriptions and line.startswith('Maintainers'):
@@ -76,9 +88,25 @@ class MaintainersParser:
#
# Handle profile entries - either as files or as https refs
#
- match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ match = re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line)
if match:
- entry = os.path.relpath(match.group(1), base_path)
+ name = "".join(match.groups())
+ entry = os.path.relpath(base_dir + name, app_dir)
+
+ full_name = os.path.join(base_dir, name)
+ path = os.path.relpath(full_name, app_dir)
+ #
+ # When SPHINXDIRS is used, it will try to reference files
+ # outside srctree, causing warnings. To avoid that, point
+ # to the latest official documentation
+ #
+ if path.startswith("../"):
+ entry = KERNELDOC_URL + match.group(2) + ".html"
+ else:
+ entry = "/" + entry
+
+ print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
+
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -189,10 +217,10 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
- output = MaintainersParser(base_path, path).output
+ output = MaintainersParser(path).output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -213,11 +241,10 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -227,27 +254,20 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- maint = MaintainersParser(base_path, path)
+ maint = MaintainersParser(path)
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
-
- for profile, entry in maint.profile_entries.items():
+ for profile, entry in sorted(maint.profile_entries.items()):
if entry.startswith("http"):
- if profile:
- output += f"- `{profile} <{entry}>`_\n"
- else:
- output += f"- `<{entry}>_`\n"
+ output += f"- `{profile} <{entry}>`_\n"
else:
- if profile:
- output += f"- :doc:`{profile} <{entry}>`\n"
- else:
- output += f"- :doc:`<{entry}>`\n"
+ output += f"- :doc:`{profile} <{entry}>`\n"
#
# Create a hidden TOC table with all profiles. That allows adding
@@ -261,6 +281,8 @@ class MaintainersProfile(Include):
output += "\n"
+ print(output)
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -277,11 +299,10 @@ class MaintainersProfile(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -289,6 +310,14 @@ class MaintainersProfile(Include):
return []
def setup(app):
+ global app_dir
+
+ #
+ # NOTE: we're using os.fspath() here because of a Sphinx warning:
+ # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
+ #
+ app_dir = os.fspath(app.srcdir)
+
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
return dict(
--
2.53.0
^ permalink raw reply related
* [PATCH v2 07/11] docs: maintainers_include: preserve names for files under process/
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
When a maintainer's profile is stored outside process, they're
already included on some other book and the name of the filesystem
may not be there. That's why the logic picks the name from the
subsystem's name.
However, files directly placed together with maintainers-handbooks.rst
(e.g. under Documentation/process/) is a different history: those
aren't placed anywhere, so we can keep using their own names,
letting Sphinx do his thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index f1b8d4b00c2a..948746b998a3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -76,11 +76,13 @@ class MaintainersParser:
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
fname = os.path.relpath(match.group(1), base_path)
- if fname not in self.profiles:
+ if fname.startswith("../"):
if self.profiles.get(fname) is None:
self.profiles[fname] = subsystem_name
else:
self.profiles[fname] += f", {subsystem_name}"
+ else:
+ self.profiles[fname] = None
match = re.match(r"P:\s*(https?://.*)", line)
if match:
--
2.53.0
^ permalink raw reply related
* [PATCH v2 09/11] docs: maintainers_include: improve its output
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
There are three "types" of profiles:
1. Profiles already included inside subsystem-specific documentation.
This is the most common case;
2. Profiles that are hosted externally;
3. Profiles that are at the same location as maintainer-handbooks.rst.
For (3), we need to create a TOC, as they don't exist elsewhere.
Change the logic to create TOC just for (3), prepending the
content of maintainer-handbooks with a sorted entry of all types,
before the TOC.
With such change, we can have an unique sorted list of profiles,
having the subsystem names used there listed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 76 +++++++++++----------
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 7ab921820612..5413c1350bba 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,7 +21,7 @@ import sys
import re
import os.path
-from textwrap import indent
+from glob import glob
from docutils import statemachine
from docutils.parsers.rst import Directive
@@ -36,8 +36,8 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = {}
- self.profile_urls = {}
+ self.profile_toc = set()
+ self.profile_entries = {}
result = list()
result.append(".. _maintainers:")
@@ -73,26 +73,24 @@ class MaintainersParser:
# Drop needless input whitespace.
line = line.rstrip()
+ #
+ # Handle profile entries - either as files or as https refs
+ #
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
- fname = os.path.relpath(match.group(1), base_path)
- if fname.startswith("../"):
- if self.profiles.get(fname) is None:
- self.profiles[fname] = subsystem_name
- else:
- self.profiles[fname] += f", {subsystem_name}"
+ entry = os.path.relpath(match.group(1), base_path)
+ if "*" in entry:
+ for e in glob(entry):
+ self.profile_toc.add(e)
+ self.profile_entries[subsystem_name] = e
else:
- self.profiles[fname] = None
-
- match = re.match(r"P:\s*(https?://.*)", line)
- if match:
- url = match.group(1).strip()
- if url not in self.profile_urls:
- if self.profile_urls.get(url) is None:
- self.profile_urls[url] = subsystem_name
- else:
- self.profile_urls[url] += f", {subsystem_name}"
-
+ self.profile_toc.add(entry)
+ self.profile_entries[subsystem_name] = entry
+ else:
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ entry = match.group(1).strip()
+ self.profile_entries[subsystem_name] = entry
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -234,26 +232,32 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
- output = ".. toctree::\n"
- output += " :maxdepth: 1\n\n"
+ #
+ # Produce a list with all maintainer profiles, sorted by subsystem name
+ #
+ output = ""
- items = sorted(maint.profiles.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for fname, profile in items:
- if profile:
- output += f" {profile} <{fname}>\n"
+ for profile, entry in maint.profile_entries.items():
+ if entry.startswith("http"):
+ if profile:
+ output += f"- `{profile} <{entry}>`_\n"
+ else:
+ output += f"- `<{entry}>_`\n"
else:
- output += f" {fname}\n"
+ if profile:
+ output += f"- :doc:`{profile} <{entry}>`\n"
+ else:
+ output += f"- :doc:`<{entry}>`\n"
- output += "\n**External profiles**\n\n"
+ #
+ # Create a hidden TOC table with all profiles. That allows adding
+ # profiles without needing to add them on any index.rst file.
+ #
+ output += "\n.. toctree::\n"
+ output += " :hidden:\n\n"
- items = sorted(maint.profile_urls.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for url, profile in items:
- if profile:
- output += f"- {profile} <{url}>\n"
- else:
- output += f"- {url}\n"
+ for fname in maint.profile_toc:
+ output += f" {fname}\n"
output += "\n"
--
2.53.0
^ permalink raw reply related
* [PATCH v2 08/11] docs: maintainers_include: Only show main entry for profiles
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Instead of showing as a "Contents:" with 2 identation levels,
drop its title and show profiles as a list of entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainer-handbooks.rst | 2 --
Documentation/sphinx/maintainers_include.py | 2 +-
2 files changed, 1 insertion(+), 3 deletions(-)
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 531985a0fae8..3821e78aefc0 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
-Contents:
-
.. maintainers-profile-toc::
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 948746b998a3..7ab921820612 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -235,7 +235,7 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
- output += " :maxdepth: 2\n\n"
+ output += " :maxdepth: 1\n\n"
items = sorted(maint.profiles.items(),
key=lambda kv: (kv[1] or "", kv[0]))
--
2.53.0
^ permalink raw reply related
* [PATCH v2 06/11] docs: maintainers_include: add external profile URLs
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Some subsystem profiles are maintained elsewhere. Add them to
the output.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 28 +++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index cf428db7599c..f1b8d4b00c2a 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,6 +37,7 @@ class MaintainersParser:
def __init__(self, base_path, path):
self.profiles = {}
+ self.profile_urls = {}
result = list()
result.append(".. _maintainers:")
@@ -81,6 +82,16 @@ class MaintainersParser:
else:
self.profiles[fname] += f", {subsystem_name}"
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ url = match.group(1).strip()
+ if url not in self.profile_urls:
+ if self.profile_urls.get(url) is None:
+ self.profile_urls[url] = subsystem_name
+ else:
+ self.profile_urls[url] += f", {subsystem_name}"
+
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -219,18 +230,31 @@ class MaintainersProfile(Include):
def emit(self, base_path, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- profiles = MaintainersParser(base_path, path).profiles
+ maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ items = sorted(maint.profiles.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
for fname, profile in items:
if profile:
output += f" {profile} <{fname}>\n"
else:
output += f" {fname}\n"
+ output += "\n**External profiles**\n\n"
+
+ items = sorted(maint.profile_urls.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
+ for url, profile in items:
+ if profile:
+ output += f"- {profile} <{url}>\n"
+ else:
+ output += f"- {url}\n"
+
+ output += "\n"
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
--
2.53.0
^ permalink raw reply related
* [PATCH v2 11/11] docs: maintainers_include: parse MAINTAINERS just once
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Change the logic to parse MAINTAINERS file content just once,
while still allowing using it multiple times.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 61 +++++++--------------
1 file changed, 21 insertions(+), 40 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index ae52e8198750..436e7ac42ffc 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,14 +37,13 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-app_dir = "."
+maint_parser = None
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, path):
- global app_dir
-
+ def __init__(self, app_dir, path):
+ self.path = path
self.profile_toc = set()
self.profile_entries = {}
@@ -67,7 +66,6 @@ class MaintainersParser:
subsystem_name = None
base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
- print("BASE DIR", base_dir)
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -105,8 +103,6 @@ class MaintainersParser:
else:
entry = "/" + entry
- print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
-
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -217,14 +213,17 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
+ global maint_parser
- output = MaintainersParser(path).output
+ path = maint_parser.path
+ output = maint_parser.output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -232,19 +231,8 @@ class MaintainersInclude(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -254,16 +242,17 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines looking for profile entries"""
+ global maint_parser
- maint = MaintainersParser(path)
+ path = maint_parser.path
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
- for profile, entry in sorted(maint.profile_entries.items()):
+ for profile, entry in sorted(maint_parser.profile_entries.items()):
if entry.startswith("http"):
output += f"- `{profile} <{entry}>`_\n"
else:
@@ -276,13 +265,12 @@ class MaintainersProfile(Include):
output += "\n.. toctree::\n"
output += " :hidden:\n\n"
- for fname in maint.profile_toc:
+ for fname in maint_parser.profile_toc:
output += f" {fname}\n"
output += "\n"
- print(output)
-
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -290,19 +278,8 @@ class MaintainersProfile(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -310,13 +287,17 @@ class MaintainersProfile(Include):
return []
def setup(app):
- global app_dir
+ global maint_parser
#
# NOTE: we're using os.fspath() here because of a Sphinx warning:
# RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
#
app_dir = os.fspath(app.srcdir)
+ srctree = os.path.abspath(os.environ["srctree"])
+ path = os.path.join(srctree, "MAINTAINERS")
+
+ maint_parser = MaintainersParser(app_dir, path)
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
--
2.53.0
^ permalink raw reply related
* [PATCH v2 04/11] docs: auto-generate maintainer entry profile links
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Albert Ou, Alexandre Ghiti, Dan Williams, Mauro Carvalho Chehab,
Palmer Dabbelt, Paul Walmsley, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Instead of manually creating a TOC tree for them, use the new
tag to auto-generate its TOC.
Co-developed-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <9228f77b0339b8e5dea4a201ab6d4feb30cef5c2.1776176108.git.mchehab+huawei@kernel.org>
---
.../maintainer/maintainer-entry-profile.rst | 24 ++++---------------
.../process/maintainer-handbooks.rst | 19 ++++++++-------
2 files changed, 14 insertions(+), 29 deletions(-)
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 6020d188e13d..58e2af333692 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also
list how review works for this code area and methods to get feedback
that are not directly from the maintainer.
-Existing profiles
------------------
+Maintainer Handbooks
+--------------------
-For now, existing maintainer profiles are listed here; we will likely want
-to do something different in the near future.
-
-.. toctree::
- :maxdepth: 1
-
- ../doc-guide/maintainer-profile
- ../nvdimm/maintainer-entry-profile
- ../arch/riscv/patch-acceptance
- ../process/maintainer-soc
- ../process/maintainer-soc-clean-dts
- ../driver-api/media/maintainer-entry-profile
- ../process/maintainer-netdev
- ../driver-api/vfio-pci-device-specific-driver-acceptance
- ../nvme/feature-and-quirk-policy
- ../filesystems/nfs/nfsd-maintainer-entry-profile
- ../filesystems/xfs/xfs-maintainer-entry-profile
- ../mm/damon/maintainer-profile
+For examples of other subsystem handbooks see
+Documentation/process/maintainer-handbooks.rst.
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 3d72ad25fc6a..531985a0fae8 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -7,14 +7,15 @@ The purpose of this document is to provide subsystem specific information
which is supplementary to the general development process handbook
:ref:`Documentation/process <development_process_main>`.
+For developers, see below for all the known subsystem specific guides.
+If the subsystem you are contributing to does not have a guide listed
+here, it is fair to seek clarification of questions raised in
+Documentation/maintainer/maintainer-entry-profile.rst.
+
+For maintainers, consider documenting additional requirements and
+expectations if submissions routinely overlook specific submission
+criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
+
Contents:
-.. toctree::
- :numbered:
- :maxdepth: 2
-
- maintainer-netdev
- maintainer-soc
- maintainer-soc-clean-dts
- maintainer-tip
- maintainer-kvm-x86
+.. maintainers-profile-toc::
--
2.53.0
^ permalink raw reply related
* [PATCH v2 00/11] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-riscv,
workflows, Alexandre Ghiti, Shuah Khan, Randy Dunlap,
Dan Williams
Hi Jon,
This patch series change the way maintainer entry profile links
are added to the documentation. Instead of having an entry for
each of them at an ReST file, get them from MAINTAINERS content.
That should likely make easier to maintain, as there will be a single
point to place all such profiles.
The output is a per-subsystem sorted (*) series of links shown as a
list like this:
- Arm And Arm64 Soc Sub-Architectures (Common Parts)
- Arm/Samsung S3C, S5P And Exynos Arm Architectures
- Arm/Tesla Fsd Soc Support
...
- Xfs Filesystem
Please notice that the series is doing one logical change per patch.
I could have merged some changes altogether, but I opted doing it
in small steps to help reviews. If you prefer, feel free to merge
maintainers_include changes on merge.
There is one interesting side effect of this series: there is no
need to add rst files containing profiles inside a TOC tree: Just
creating the file anywhere inside Documentation and adding a P entry
is enough. Adding them to a TOC won't hurt.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
(*) At the end, I opted to use sorted(), just to ensure it, even
knowing that MAINTAINER entries are supposed to be sorted, as
the cost of sorting ~20 already-sorted entries is negligible.
---
v2:
- I placed the to MAINTAINERS changes at the beginning.
- fix a bug when O=DOCS is used;
- proper handle glob "P" entries (just in case, no profiles use it ATM);
- when SPHINXDIRS=process, instead of producing warnings, point to
entries at https://docs.kernel.org;
- MAINTAINERS parsing now happens just once;
- The output won't be numered for entries inside numered TOC trees;
- TOC tree is now hidden;
- instead of display a TOC tree, it shows a list of profiles,
ordered and named after file system name taken from MAINTAINERS file;
- At the output list, both https and file profiles are shown the same
way.
Mauro Carvalho Chehab (11):
MAINTAINERS: add an entry for media maintainers profile
MAINTAINERS: add maintainer-tip.rst to X86
docs: maintainers_include: auto-generate maintainer profile TOC
docs: auto-generate maintainer entry profile links
docs: maintainers_include: use a better title for profiles
docs: maintainers_include: add external profile URLs
docs: maintainers_include: preserve names for files under process/
docs: maintainers_include: Only show main entry for profiles
docs: maintainers_include: improve its output
docs: maintainers_include: fix support for O=dir
docs: maintainers_include: parse MAINTAINERS just once
.../maintainer/maintainer-entry-profile.rst | 24 +--
.../process/maintainer-handbooks.rst | 17 +-
Documentation/sphinx/maintainers_include.py | 161 +++++++++++++++---
MAINTAINERS | 2 +
4 files changed, 150 insertions(+), 54 deletions(-)
--
2.53.0
^ permalink raw reply
* [PATCH v2 05/11] docs: maintainers_include: use a better title for profiles
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
As we're picking the name of the subsystem from MAINTAINERS,
also use its subsystem name for the titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 1dac83bf1a65..cf428db7599c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -36,7 +36,7 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = list()
+ self.profiles = {}
result = list()
result.append(".. _maintainers:")
@@ -54,6 +54,7 @@ class MaintainersParser:
prev = None
field_prev = ""
field_content = ""
+ subsystem_name = None
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -75,7 +76,10 @@ class MaintainersParser:
if match:
fname = os.path.relpath(match.group(1), base_path)
if fname not in self.profiles:
- self.profiles.append(fname)
+ if self.profiles.get(fname) is None:
+ self.profiles[fname] = subsystem_name
+ else:
+ self.profiles[fname] += f", {subsystem_name}"
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -112,6 +116,8 @@ class MaintainersParser:
output = field_content + "\n\n"
field_content = ""
+ subsystem_name = line.title()
+
# Collapse whitespace in subsystem name.
heading = re.sub(r"\s+", " ", line)
output = output + "%s\n%s" % (heading, "~" * len(heading))
@@ -217,7 +223,13 @@ class MaintainersProfile(Include):
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- output += indent("\n".join(profiles), " ")
+
+ items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ for fname, profile in items:
+ if profile:
+ output += f" {profile} <{fname}>\n"
+ else:
+ output += f" {fname}\n"
self.state_machine.insert_input(statemachine.string2lines(output), path)
--
2.53.0
^ permalink raw reply related
* [PATCH v2 02/11] MAINTAINERS: add maintainer-tip.rst to X86
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
The X86 subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <970434c647aa1e1e9a81c87b4d5fed934d4018a7.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 620219e48f98..a85fcae5f56e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -28560,6 +28560,7 @@ M: Ingo Molnar <mingo@redhat.com>
M: Borislav Petkov <bp@alien8.de>
M: Dave Hansen <dave.hansen@linux.intel.com>
M: x86@kernel.org
+P: Documentation/process/maintainer-tip.rst
R: "H. Peter Anvin" <hpa@zytor.com>
L: linux-kernel@vger.kernel.org
S: Maintained
--
2.53.0
^ permalink raw reply related
* [PATCH v2 03/11] docs: maintainers_include: auto-generate maintainer profile TOC
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Add a feature to allow auto-generating media entry profiles from the
corresponding field inside MAINTAINERS file(s).
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++----
1 file changed, 76 insertions(+), 17 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 519ad18685b2..1dac83bf1a65 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,6 +21,8 @@ import sys
import re
import os.path
+from textwrap import indent
+
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
@@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-def setup(app):
- app.add_directive("maintainers-include", MaintainersInclude)
- return dict(
- version = __version__,
- parallel_read_safe = True,
- parallel_write_safe = True
- )
+class MaintainersParser:
+ """Parse MAINTAINERS file(s) content"""
-class MaintainersInclude(Include):
- """MaintainersInclude (``maintainers-include``) directive"""
- required_arguments = 0
-
- def parse_maintainers(self, path):
- """Parse all the MAINTAINERS lines into ReST for human-readability"""
+ def __init__(self, base_path, path):
+ self.profiles = list()
result = list()
result.append(".. _maintainers:")
@@ -78,6 +71,12 @@ class MaintainersInclude(Include):
# Drop needless input whitespace.
line = line.rstrip()
+ match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ if match:
+ fname = os.path.relpath(match.group(1), base_path)
+ if fname not in self.profiles:
+ self.profiles.append(fname)
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -165,12 +164,23 @@ class MaintainersInclude(Include):
for separated in field_content.split('\n'):
result.append(separated)
- output = "\n".join(result)
+ self.output = "\n".join(result)
+
+ # Create a TOC class
+
+class MaintainersInclude(Include):
+ """MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ output = MaintainersParser(base_path, path).output
+
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
- self.state_machine.insert_input(
- statemachine.string2lines(output), path)
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
@@ -186,12 +196,61 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.parse_maintainers(path)
+ lines = self.emit(base_path, path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
+class MaintainersProfile(Include):
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines looking for profile entries"""
+
+ profiles = MaintainersParser(base_path, path).profiles
+
+ output = ".. toctree::\n"
+ output += " :maxdepth: 2\n\n"
+ output += indent("\n".join(profiles), " ")
+
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # Append "MAINTAINERS"
+ path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
+
+ try:
+ self.state.document.settings.record_dependencies.add(path)
+ lines = self.emit(base_path, path)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.53.0
^ permalink raw reply related
* [PATCH v2 01/11] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
The media subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index f0b106a4dd96..620219e48f98 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16115,6 +16115,7 @@ S: Maintained
W: https://linuxtv.org
Q: http://patchwork.kernel.org/project/linux-media/list/
T: git git://linuxtv.org/media.git
+P: Documentation/driver-api/media/maintainer-entry-profile.rst
F: Documentation/admin-guide/media/
F: Documentation/devicetree/bindings/media/
F: Documentation/driver-api/media/
--
2.53.0
^ permalink raw reply related
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Randy Dunlap @ 2026-04-16 21:32 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley, linux-doc, linux-kernel, linux-riscv, workflows,
Alexandre Ghiti, Shuah Khan, Dan Williams
In-Reply-To: <20260416100026.3df67a72@foz.lan>
On 4/16/26 1:00 AM, Mauro Carvalho Chehab wrote:
> On Wed, 15 Apr 2026 13:41:16 -0700
> Randy Dunlap <rdunlap@infradead.org> wrote:
>
>> Hi Mauro,
>>
>> Thanks for tackling this issue.
>>
>> On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
>>> Date: Tue, 14 Apr 2026 16:29:03 +0200
>>> From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
>>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
>>> Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
>>>
>>> Hi Dan/Jon,
>>>
>>> This patch series change the way maintainer entry profile links
>>> are added to the documentation. Instead of having an entry for
>>> each of them at an ReST file, get them from MAINTAINERS content.
>>>
>>> That should likely make easier to maintain, as there will be a single
>>> point to place all such profiles.
>>>
>>> On this version, I added Dan's text to patch 4.
>>>
>>> I also added a couple of other patches to improve its output. While
>>> I could have them merged at the first patch, I opted to make them
>>> separate, as, in case of problems or needed changes, it would be
>>> easier to revert or modify the corresponding logic. Also, it should
>>> be better to review, in case one wants some changes there.
>>>
>>> The main changes against RFC are:
>>>
>>> - now, the TOC will be presented with 1 depth identation level,
>>> meaning that it would look like a list;
>>> - for files outside Documentation/process, it will use the name of
>>> the subsystem with title capitalization for the name of the
>>> profile entry;
>>> - the logic also parses and produces a list of profiles that are
>>> maintained elsewhere, picking its http/https link;
>>> - entries are now better sorted: first by subsystem name, then
>>> by its name.
>>>
>>> Suggested-by: Dan Williams <djbw@kernel.org>
>>> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
>>>
>>> Mauro Carvalho Chehab (8):
>>> docs: maintainers_include: auto-generate maintainer profile TOC
>>> MAINTAINERS: add an entry for media maintainers profile
>>> MAINTAINERS: add maintainer-tip.rst to X86
>>> docs: auto-generate maintainer entry profile links
>>> docs: maintainers_include: use a better title for profiles
>>> docs: maintainers_include: add external profile URLs
>>> docs: maintainers_include: preserve names for files under process/
>>> docs: maintainers_include: Only show main entry for profiles
>>>
>>> .../maintainer/maintainer-entry-profile.rst | 24 +---
>>> .../process/maintainer-handbooks.rst | 17 ++-
>>> Documentation/sphinx/maintainers_include.py | 131 +++++++++++++++---
>>> MAINTAINERS | 2 +
>>> 4 files changed, 128 insertions(+), 46 deletions(-)
>>
>> When building htmldocs with O=DOCS, I get a bunch of warnings.
>> I tested against today's linux-next tree.
>>
>> The 'make O=DOCS htmldocs' warnings are (subset of all warnings):
>>
>> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
>> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
>> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
>> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
>> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]
>>
>> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
>> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
>> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
>> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
>> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
>> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
>>
>> linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
>> linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
>> linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
>> linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
>> linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
>
> Heh, os.path.relpath() does the wrong thing here.
>
> The enclosed patch should handle it better.
>
> Thanks,
> Mauro
>
> [PATCH] docs: maintainers_include: fix support for O=dir
>
> os.path.relpath() will do the wrong thing with O=dir, as the build
> system uses "cd <dir>" internally.
>
> Solve it by using app.srcdir, which, on normal cases, point to
> Documentation/, or, when SPHINXDIRS=process, it will be set with
> Documentation/process.
>
> While here, remove a dead code while writing maintainer profiles,
> as now all entries should have both profile and entry.
>
> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> index 5413c1350bba..fff9bdd55a56 100755
> --- a/Documentation/sphinx/maintainers_include.py
> +++ b/Documentation/sphinx/maintainers_include.py
> @@ -27,15 +27,24 @@ from docutils import statemachine
> from docutils.parsers.rst import Directive
> from docutils.parsers.rst.directives.misc import Include
>
> +#
> +# Base URL for intersphinx-like links to maintainer profiles
> +#
> +KERNELDOC_URL = "https://docs.kernel.org/"
> +
> def ErrorString(exc): # Shamelessly stolen from docutils
> return f'{exc.__class__.__name}: {exc}'
>
> __version__ = '1.0'
>
> +base_dir = "."
> +
> class MaintainersParser:
> """Parse MAINTAINERS file(s) content"""
>
> - def __init__(self, base_path, path):
> + def __init__(self, path):
> + global base_dir
> +
> self.profile_toc = set()
> self.profile_entries = {}
>
> @@ -76,9 +85,18 @@ class MaintainersParser:
> #
> # Handle profile entries - either as files or as https refs
> #
> - match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
> + match = re.match(r"P:\s*Documentation(/\S+)\.rst", line)
> if match:
> - entry = os.path.relpath(match.group(1), base_path)
> + entry = os.path.relpath(match.group(1), base_dir)
> +
> + #
> + # When SPHINXDIRS is used, it will try to reference files
> + # outside srctree, causing warnings. To avoid that, point
> + # to the latest official documentation
> + #
> + if entry.startswith("../"):
> + entry = KERNELDOC_URL + match.group(1) + ".html"
> +
> if "*" in entry:
> for e in glob(entry):
> self.profile_toc.add(e)
> @@ -189,10 +207,10 @@ class MaintainersInclude(Include):
> """MaintainersInclude (``maintainers-include``) directive"""
> required_arguments = 0
>
> - def emit(self, base_path, path):
> + def emit(self, path):
> """Parse all the MAINTAINERS lines into ReST for human-readability"""
>
> - output = MaintainersParser(base_path, path).output
> + output = MaintainersParser(path).output
>
> # For debugging the pre-rendered results...
> #print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
> @@ -213,11 +231,10 @@ class MaintainersInclude(Include):
>
> # Append "MAINTAINERS"
> path = os.path.join(path, "MAINTAINERS")
> - base_path = os.path.dirname(self.state.document.document.current_source)
>
> try:
> self.state.document.settings.record_dependencies.add(path)
> - lines = self.emit(base_path, path)
> + lines = self.emit(path)
> except IOError as error:
> raise self.severe('Problems with "%s" directive path:\n%s.' %
> (self.name, ErrorString(error)))
> @@ -227,27 +244,20 @@ class MaintainersInclude(Include):
> class MaintainersProfile(Include):
> required_arguments = 0
>
> - def emit(self, base_path, path):
> + def emit(self, path):
> """Parse all the MAINTAINERS lines looking for profile entries"""
>
> - maint = MaintainersParser(base_path, path)
> + maint = MaintainersParser(path)
>
> #
> # Produce a list with all maintainer profiles, sorted by subsystem name
> #
> output = ""
> -
> - for profile, entry in maint.profile_entries.items():
> + for profile, entry in sorted(maint.profile_entries.items()):
> if entry.startswith("http"):
> - if profile:
> - output += f"- `{profile} <{entry}>`_\n"
> - else:
> - output += f"- `<{entry}>_`\n"
> + output += f"- `{profile} <{entry}>`_\n"
> else:
> - if profile:
> - output += f"- :doc:`{profile} <{entry}>`\n"
> - else:
> - output += f"- :doc:`<{entry}>`\n"
> + output += f"- :doc:`{profile} <{entry}>`\n"
>
> #
> # Create a hidden TOC table with all profiles. That allows adding
> @@ -277,11 +287,10 @@ class MaintainersProfile(Include):
>
> # Append "MAINTAINERS"
> path = os.path.join(path, "MAINTAINERS")
> - base_path = os.path.dirname(self.state.document.document.current_source)
>
> try:
> self.state.document.settings.record_dependencies.add(path)
> - lines = self.emit(base_path, path)
> + lines = self.emit(path)
> except IOError as error:
> raise self.severe('Problems with "%s" directive path:\n%s.' %
> (self.name, ErrorString(error)))
> @@ -289,6 +298,15 @@ class MaintainersProfile(Include):
> return []
>
> def setup(app):
> + global base_dir
> +
> + #
> + # partition will pick the path after Documentation.
> + # NOTE: we're using os.fspath() here because of a Sphinx warning:
> + # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
> + #
> + _, _, base_dir = os.fspath(app.srcdir).partition("Documentation")
> +
> app.add_directive("maintainers-include", MaintainersInclude)
> app.add_directive("maintainers-profile-toc", MaintainersProfile)
> return dict(
With that patch I still see 6 warnings:
linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
--
~Randy
^ permalink raw reply
* Re: [PATCH net] netrom: do some basic forms of validation on incoming frames
From: Jakub Kicinski @ 2026-04-16 16:58 UTC (permalink / raw)
To: linux-hams
Cc: Chris Maness, hugh, Greg KH, Kuniyuki Iwashima, davem, edumazet,
horms, linux-kernel, netdev, pabeni, stable, workflows, yizhe,
f6bvp, Jean-Paul Roubelat, Joerg Reuter, Andreas Koensgen,
Thomas Sailer
In-Reply-To: <CANnsUMFVg9nZnJ_He38O9Ui1YUM_Je7MGO-y_J+oW=TG3jV1bA@mail.gmail.com>
On Sun, 12 Apr 2026 05:56:50 -0700 Chris Maness wrote:
> Thanks for your work, Hugh.
Hi good folks of hamradio.
There was a blip of activity after this thread started but now core
networking maintainers are back to reviewing all the fixes themselves
again.
We would like y'all to set up a git tree so that you can handle all the
incoming AI patches, and send them out as a pull request. This is how
wifi, bluetooth etc. operate. You already have a mailing list so that's
good.
We do not have the capacity to review all the AI generated fixes, and
ignoring security fixes does not feel like an option. I'm planning to
send a PR early next week, shedding some low usage / high CVE count code
I hope you can have the tree in place by then.
^ permalink raw reply
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-16 8:00 UTC (permalink / raw)
To: Randy Dunlap
Cc: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley, linux-doc, linux-kernel, linux-riscv, workflows,
Alexandre Ghiti, Shuah Khan, Dan Williams
In-Reply-To: <88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org>
On Wed, 15 Apr 2026 13:41:16 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
> Hi Mauro,
>
> Thanks for tackling this issue.
>
> On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
> > Date: Tue, 14 Apr 2026 16:29:03 +0200
> > From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
> > Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
> > Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
> >
> > Hi Dan/Jon,
> >
> > This patch series change the way maintainer entry profile links
> > are added to the documentation. Instead of having an entry for
> > each of them at an ReST file, get them from MAINTAINERS content.
> >
> > That should likely make easier to maintain, as there will be a single
> > point to place all such profiles.
> >
> > On this version, I added Dan's text to patch 4.
> >
> > I also added a couple of other patches to improve its output. While
> > I could have them merged at the first patch, I opted to make them
> > separate, as, in case of problems or needed changes, it would be
> > easier to revert or modify the corresponding logic. Also, it should
> > be better to review, in case one wants some changes there.
> >
> > The main changes against RFC are:
> >
> > - now, the TOC will be presented with 1 depth identation level,
> > meaning that it would look like a list;
> > - for files outside Documentation/process, it will use the name of
> > the subsystem with title capitalization for the name of the
> > profile entry;
> > - the logic also parses and produces a list of profiles that are
> > maintained elsewhere, picking its http/https link;
> > - entries are now better sorted: first by subsystem name, then
> > by its name.
> >
> > Suggested-by: Dan Williams <djbw@kernel.org>
> > Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
> >
> > Mauro Carvalho Chehab (8):
> > docs: maintainers_include: auto-generate maintainer profile TOC
> > MAINTAINERS: add an entry for media maintainers profile
> > MAINTAINERS: add maintainer-tip.rst to X86
> > docs: auto-generate maintainer entry profile links
> > docs: maintainers_include: use a better title for profiles
> > docs: maintainers_include: add external profile URLs
> > docs: maintainers_include: preserve names for files under process/
> > docs: maintainers_include: Only show main entry for profiles
> >
> > .../maintainer/maintainer-entry-profile.rst | 24 +---
> > .../process/maintainer-handbooks.rst | 17 ++-
> > Documentation/sphinx/maintainers_include.py | 131 +++++++++++++++---
> > MAINTAINERS | 2 +
> > 4 files changed, 128 insertions(+), 46 deletions(-)
>
> When building htmldocs with O=DOCS, I get a bunch of warnings.
> I tested against today's linux-next tree.
>
> The 'make O=DOCS htmldocs' warnings are (subset of all warnings):
>
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]
>
> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
>
> linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
> linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
> linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
Heh, os.path.relpath() does the wrong thing here.
The enclosed patch should handle it better.
Thanks,
Mauro
[PATCH] docs: maintainers_include: fix support for O=dir
os.path.relpath() will do the wrong thing with O=dir, as the build
system uses "cd <dir>" internally.
Solve it by using app.srcdir, which, on normal cases, point to
Documentation/, or, when SPHINXDIRS=process, it will be set with
Documentation/process.
While here, remove a dead code while writing maintainer profiles,
as now all entries should have both profile and entry.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 5413c1350bba..fff9bdd55a56 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -27,15 +27,24 @@ from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
+#
+# Base URL for intersphinx-like links to maintainer profiles
+#
+KERNELDOC_URL = "https://docs.kernel.org/"
+
def ErrorString(exc): # Shamelessly stolen from docutils
return f'{exc.__class__.__name}: {exc}'
__version__ = '1.0'
+base_dir = "."
+
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, base_path, path):
+ def __init__(self, path):
+ global base_dir
+
self.profile_toc = set()
self.profile_entries = {}
@@ -76,9 +85,18 @@ class MaintainersParser:
#
# Handle profile entries - either as files or as https refs
#
- match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ match = re.match(r"P:\s*Documentation(/\S+)\.rst", line)
if match:
- entry = os.path.relpath(match.group(1), base_path)
+ entry = os.path.relpath(match.group(1), base_dir)
+
+ #
+ # When SPHINXDIRS is used, it will try to reference files
+ # outside srctree, causing warnings. To avoid that, point
+ # to the latest official documentation
+ #
+ if entry.startswith("../"):
+ entry = KERNELDOC_URL + match.group(1) + ".html"
+
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -189,10 +207,10 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
- output = MaintainersParser(base_path, path).output
+ output = MaintainersParser(path).output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -213,11 +231,10 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -227,27 +244,20 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- maint = MaintainersParser(base_path, path)
+ maint = MaintainersParser(path)
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
-
- for profile, entry in maint.profile_entries.items():
+ for profile, entry in sorted(maint.profile_entries.items()):
if entry.startswith("http"):
- if profile:
- output += f"- `{profile} <{entry}>`_\n"
- else:
- output += f"- `<{entry}>_`\n"
+ output += f"- `{profile} <{entry}>`_\n"
else:
- if profile:
- output += f"- :doc:`{profile} <{entry}>`\n"
- else:
- output += f"- :doc:`<{entry}>`\n"
+ output += f"- :doc:`{profile} <{entry}>`\n"
#
# Create a hidden TOC table with all profiles. That allows adding
@@ -277,11 +287,10 @@ class MaintainersProfile(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -289,6 +298,15 @@ class MaintainersProfile(Include):
return []
def setup(app):
+ global base_dir
+
+ #
+ # partition will pick the path after Documentation.
+ # NOTE: we're using os.fspath() here because of a Sphinx warning:
+ # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
+ #
+ _, _, base_dir = os.fspath(app.srcdir).partition("Documentation")
+
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
return dict(
^ permalink raw reply related
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Randy Dunlap @ 2026-04-15 20:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Albert Ou, Jonathan Corbet,
Mauro Carvalho Chehab, Palmer Dabbelt, Paul Walmsley
Cc: linux-doc, linux-kernel, linux-riscv, workflows, Alexandre Ghiti,
Shuah Khan, Dan Williams
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
Hi Mauro,
Thanks for tackling this issue.
On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
> Date: Tue, 14 Apr 2026 16:29:03 +0200
> From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
> Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
>
> Hi Dan/Jon,
>
> This patch series change the way maintainer entry profile links
> are added to the documentation. Instead of having an entry for
> each of them at an ReST file, get them from MAINTAINERS content.
>
> That should likely make easier to maintain, as there will be a single
> point to place all such profiles.
>
> On this version, I added Dan's text to patch 4.
>
> I also added a couple of other patches to improve its output. While
> I could have them merged at the first patch, I opted to make them
> separate, as, in case of problems or needed changes, it would be
> easier to revert or modify the corresponding logic. Also, it should
> be better to review, in case one wants some changes there.
>
> The main changes against RFC are:
>
> - now, the TOC will be presented with 1 depth identation level,
> meaning that it would look like a list;
> - for files outside Documentation/process, it will use the name of
> the subsystem with title capitalization for the name of the
> profile entry;
> - the logic also parses and produces a list of profiles that are
> maintained elsewhere, picking its http/https link;
> - entries are now better sorted: first by subsystem name, then
> by its name.
>
> Suggested-by: Dan Williams <djbw@kernel.org>
> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
>
> Mauro Carvalho Chehab (8):
> docs: maintainers_include: auto-generate maintainer profile TOC
> MAINTAINERS: add an entry for media maintainers profile
> MAINTAINERS: add maintainer-tip.rst to X86
> docs: auto-generate maintainer entry profile links
> docs: maintainers_include: use a better title for profiles
> docs: maintainers_include: add external profile URLs
> docs: maintainers_include: preserve names for files under process/
> docs: maintainers_include: Only show main entry for profiles
>
> .../maintainer/maintainer-entry-profile.rst | 24 +---
> .../process/maintainer-handbooks.rst | 17 ++-
> Documentation/sphinx/maintainers_include.py | 131 +++++++++++++++---
> MAINTAINERS | 2 +
> 4 files changed, 128 insertions(+), 46 deletions(-)
When building htmldocs with O=DOCS, I get a bunch of warnings.
I tested against today's linux-next tree.
The 'make O=DOCS htmldocs' warnings are (subset of all warnings):
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]
linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
--
~Randy
^ permalink raw reply
* Re: maintainer profiles
From: Mauro Carvalho Chehab @ 2026-04-15 11:43 UTC (permalink / raw)
To: Randy Dunlap
Cc: Linux Documentation, Linux Kernel Mailing List, Jonathan Corbet,
Linux Kernel Workflows
In-Reply-To: <d8804a85-dd2b-481e-903f-c6fea5d24c97@infradead.org>
On Sat, 11 Apr 2026 16:54:00 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
> Also, does anyone know why some of these profiles are numbered and some
> are not? See
> https://docs.kernel.org/maintainer/maintainer-entry-profile.html#existing-profiles
> for odd numbering.
Patch 9/8 fixes it, while solving other issues:
- https://lore.kernel.org/linux-doc/cfff2b313d1f79a5919f400020a1b1a4064a7143.1776252056.git.mchehab+huawei@kernel.org/T/#u
Basically, it creates a hidden TOC which is not displayed, creating
this ReST output:
- :doc:`Arm And Arm64 Soc Sub-Architectures (Common Parts) <maintainer-soc>`
- :doc:`Arm/Samsung S3C, S5P And Exynos Arm Architectures <maintainer-soc-clean-dts>`
- :doc:`Arm/Tesla Fsd Soc Support <maintainer-soc-clean-dts>`
- `Audit Subsystem <https://github.com/linux-audit/audit-kernel/blob/main/README.md>`_
- :doc:`Damon <../mm/damon/maintainer-profile>`
- :doc:`Documentation <../doc-guide/maintainer-profile>`
- :doc:`Google Tensor Soc Support <maintainer-soc-clean-dts>`
- :doc:`Kernel Nfsd, Sunrpc, And Lockd Servers <../filesystems/nfs/nfsd-maintainer-entry-profile>`
- :doc:`Kernel Virtual Machine For X86 (Kvm/X86) <maintainer-kvm-x86>`
- :doc:`Libnvdimm Btt: Block Translation Table <../nvdimm/maintainer-entry-profile>`
- :doc:`Libnvdimm Pmem: Persistent Memory Driver <../nvdimm/maintainer-entry-profile>`
- :doc:`Libnvdimm: Non-Volatile Memory Device Subsystem <../nvdimm/maintainer-entry-profile>`
- :doc:`Media Input Infrastructure (V4L/Dvb) <../driver-api/media/maintainer-entry-profile>`
- :doc:`Networking Drivers <maintainer-netdev>`
- :doc:`Networking [General] <maintainer-netdev>`
- :doc:`Risc-V Architecture <../arch/riscv/patch-acceptance>`
- `Rust <https://rust-for-linux.com/contributing>`_
- `Security Subsystem <https://github.com/LinuxSecurityModule/kernel/blob/main/README.md>`_
- `Selinux Security Module <https://github.com/SELinuxProject/selinux-kernel/blob/main/README.md>`_
- :doc:`Vfio Pci Device Specific Drivers <../driver-api/vfio-pci-device-specific-driver-acceptance>`
- :doc:`X86 Architecture (32-Bit And 64-Bit) <maintainer-tip>`
- :doc:`Xfs Filesystem <../filesystems/xfs/xfs-maintainer-entry-profile>`
.. toctree::
:hidden:
../filesystems/xfs/xfs-maintainer-entry-profile
../driver-api/vfio-pci-device-specific-driver-acceptance
maintainer-netdev
../nvdimm/maintainer-entry-profile
maintainer-soc
maintainer-soc-clean-dts
../doc-guide/maintainer-profile
maintainer-kvm-x86
../mm/damon/maintainer-profile
../driver-api/media/maintainer-entry-profile
../arch/riscv/patch-acceptance
../filesystems/nfs/nfsd-maintainer-entry-profile
maintainer-tip
E.g. instead of showing the contents of the TOC tree, it shows a
per-subsystem sorted list of items. The TOC tree is used there just
to avoid warnings that a .rst file is not placed on a TOC.
The advantage of such approach is that there's now one item at
the list for each "P:" tag at MAINTAINERS. All of them are
displayed using the name of the subsystem as described there,
e.g. it outputs:
• Arm And Arm64 Soc Sub-Architectures (Common Parts)
• Arm/Samsung S3C, S5P And Exynos Arm Architectures
• Arm/Tesla Fsd Soc Support
• Audit Subsystem
• Damon
• Documentation
• Google Tensor Soc Support
• Kernel Nfsd, Sunrpc, And Lockd Servers
• Kernel Virtual Machine For X86 (Kvm/X86)
• Libnvdimm Btt: Block Translation Table
• Libnvdimm Pmem: Persistent Memory Driver
• Libnvdimm: Non-Volatile Memory Device Subsystem
• Media Input Infrastructure (V4L/Dvb)
• Networking Drivers
• Networking [General]
• Risc-V Architecture
• Rust
• Security Subsystem
• Selinux Security Module
• Vfio Pci Device Specific Drivers
• X86 Architecture (32-Bit And 64-Bit)
• Xfs Filesystem
Each of entry there with either a cross-reference to a document or
with a reference to an external site.
Thanks,
Mauro
^ permalink raw reply
* [PATCH 8/8] docs: maintainers_include: Only show main entry for profiles
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
Instead of showing as a "Contents:" with 2 identation levels,
drop its title and show profiles as a list of entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainer-handbooks.rst | 2 --
Documentation/sphinx/maintainers_include.py | 2 +-
2 files changed, 1 insertion(+), 3 deletions(-)
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 531985a0fae8..3821e78aefc0 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
-Contents:
-
.. maintainers-profile-toc::
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 948746b998a3..7ab921820612 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -235,7 +235,7 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
- output += " :maxdepth: 2\n\n"
+ output += " :maxdepth: 1\n\n"
items = sorted(maint.profiles.items(),
key=lambda kv: (kv[1] or "", kv[0]))
--
2.53.0
^ permalink raw reply related
* [PATCH 2/8] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
The media subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index f0b106a4dd96..620219e48f98 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16115,6 +16115,7 @@ S: Maintained
W: https://linuxtv.org
Q: http://patchwork.kernel.org/project/linux-media/list/
T: git git://linuxtv.org/media.git
+P: Documentation/driver-api/media/maintainer-entry-profile.rst
F: Documentation/admin-guide/media/
F: Documentation/devicetree/bindings/media/
F: Documentation/driver-api/media/
--
2.53.0
^ permalink raw reply related
* [PATCH 7/8] docs: maintainers_include: preserve names for files under process/
From: Mauro Carvalho Chehab @ 2026-04-15 8:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776242739.git.mchehab+huawei@kernel.org>
When a maintainer's profile is stored outside process, they're
already included on some other book and the name of the filesystem
may not be there. That's why the logic picks the name from the
subsystem's name.
However, files directly placed together with maintainers-handbooks.rst
(e.g. under Documentation/process/) is a different history: those
aren't placed anywhere, so we can keep using their own names,
letting Sphinx do his thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index f1b8d4b00c2a..948746b998a3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -76,11 +76,13 @@ class MaintainersParser:
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
fname = os.path.relpath(match.group(1), base_path)
- if fname not in self.profiles:
+ if fname.startswith("../"):
if self.profiles.get(fname) is None:
self.profiles[fname] = subsystem_name
else:
self.profiles[fname] += f", {subsystem_name}"
+ else:
+ self.profiles[fname] = None
match = re.match(r"P:\s*(https?://.*)", line)
if match:
--
2.53.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox