[REGRESSION] Unexpected section title false positive warnings on DOC: directive

[REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 3127 bytes --]

Hi,

Building htmldocs on docs-next currenly produces about 50 new warnings; which
all of them are unexpected section title on DOC: kernel-doc directive, like:

/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.

Userspace I/O
------------- [docutils]
WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
/home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.

Ring Design
----------- [docutils]
WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Ring Design' ./include/uapi/linux/target_core_user.h' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: (SEVERE/4) Unexpected section title.\n\nRing Design\n-----------')

These turns out to be false-positive as touching the source file in question
(e.g. drivers/target/target_core_user.c) and making htmldocs again makes the
regression go away for the corresponding docs.

Bisection (with git-bisect(1)) points to bea467aa5da1f5 ("docs: media:
v4l2-ioctl.h: document two global variables") as the first bad commit, even
though that I suspect that bdd1cf87847ff6 ("kernel-doc: add support to handle
DEFINE_ variables") may be the actual culprit (regressor).

The full bisection log:

git bisect start
# status: waiting for both good and bad commits
# bad: [7f3c3a0a9103dc92c823f27db3284ac2914e7558] MAINTAINERS: Add doc files on real-time support to Real-time Linux
git bisect bad 7f3c3a0a9103dc92c823f27db3284ac2914e7558
# status: waiting for good commit(s), bad commit known
# good: [9448598b22c50c8a5bb77a9103e2d49f134c9578] Linux 6.19-rc2
git bisect good 9448598b22c50c8a5bb77a9103e2d49f134c9578
# bad: [5188f6bd408f937d81c0c37eb59ddc1035cd912c] docs: admin: devices: /dev/sr<N> for SCSI CD-ROM
git bisect bad 5188f6bd408f937d81c0c37eb59ddc1035cd912c
# bad: [bea467aa5da1f51834501da3ac3c40204027a221] docs: media: v4l2-ioctl.h: document two global variables
git bisect bad bea467aa5da1f51834501da3ac3c40204027a221
# good: [82e87387f6e2af9f69a7528733e953fd22e815aa] Documentation: kernel-hacking: Remove comma
git bisect good 82e87387f6e2af9f69a7528733e953fd22e815aa
# good: [bdd1cf87847ff6aaadd53a185209d2bb2db72165] kernel-doc: add support to handle DEFINE_ variables
git bisect good bdd1cf87847ff6aaadd53a185209d2bb2db72165
# first bad commit: [bea467aa5da1f51834501da3ac3c40204027a221] docs: media: v4l2-ioctl.h: document two global variables

Mauro: Since you're the author of regressor, can you please take a look on it?

Thanks.

#regzbot introduced: bea467aa5da1f5

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Hi,
>
> Building htmldocs on docs-next currenly produces about 50 new warnings; which
> all of them are unexpected section title on DOC: kernel-doc directive, like:
>
> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
>
> Userspace I/O
> ------------- [docutils]
> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.

So I did not, and do not, see any of these errors; are you doing
something special to get them?

jon

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[-- Attachment #1.1: Type: text/plain, Size: 1322 bytes --]

On Tue, Jan 06, 2026 at 02:58:43PM -0700, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > Hi,
> >
> > Building htmldocs on docs-next currenly produces about 50 new warnings; which
> > all of them are unexpected section title on DOC: kernel-doc directive, like:
> >
> > /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
> >
> > Userspace I/O
> > ------------- [docutils]
> > WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
> > /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.
> 
> So I did not, and do not, see any of these errors; are you doing
> something special to get them?

Nope.

I'm running my htmldocs builds on my Arch Linux system (with Sphinx 9.0.4 and
Python 3.13.11).

Full log (tarred up) attached.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #1.2: htmldocs.log.tar.gz --]
[-- Type: application/gzip, Size: 274090 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Randy Dunlap]

On 1/7/26 5:08 AM, Bagas Sanjaya wrote:
> On Tue, Jan 06, 2026 at 02:58:43PM -0700, Jonathan Corbet wrote:
>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>>
>>> Hi,
>>>
>>> Building htmldocs on docs-next currenly produces about 50 new warnings; which
>>> all of them are unexpected section title on DOC: kernel-doc directive, like:
>>>
>>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
>>>
>>> Userspace I/O
>>> ------------- [docutils]
>>> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
>>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.
>>
>> So I did not, and do not, see any of these errors; are you doing
>> something special to get them?
> 
> Nope.
> 
> I'm running my htmldocs builds on my Arch Linux system (with Sphinx 9.0.4 and
> Python 3.13.11).
> 
> Full log (tarred up) attached.
> 
> Thanks.

Hi,
What docutils version, please?

-- 
~Randy

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1637 bytes --]

On Wed, Jan 07, 2026 at 10:19:32AM -0800, Randy Dunlap wrote:
> 
> 
> On 1/7/26 5:08 AM, Bagas Sanjaya wrote:
> > On Tue, Jan 06, 2026 at 02:58:43PM -0700, Jonathan Corbet wrote:
> >> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> >>
> >>> Hi,
> >>>
> >>> Building htmldocs on docs-next currenly produces about 50 new warnings; which
> >>> all of them are unexpected section title on DOC: kernel-doc directive, like:
> >>>
> >>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
> >>>
> >>> Userspace I/O
> >>> ------------- [docutils]
> >>> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
> >>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.
> >>
> >> So I did not, and do not, see any of these errors; are you doing
> >> something special to get them?
> > 
> > Nope.
> > 
> > I'm running my htmldocs builds on my Arch Linux system (with Sphinx 9.0.4 and
> > Python 3.13.11).
> > 
> > Full log (tarred up) attached.
> > 
> > Thanks.
> 
> Hi,
> What docutils version, please?

Mine have:

docutils (Docutils 0.21.2, Python 3.13.11, on linux)

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Randy Dunlap]

On 1/7/26 3:46 PM, Bagas Sanjaya wrote:
> On Wed, Jan 07, 2026 at 10:19:32AM -0800, Randy Dunlap wrote:
>>
>>
>> On 1/7/26 5:08 AM, Bagas Sanjaya wrote:
>>> On Tue, Jan 06, 2026 at 02:58:43PM -0700, Jonathan Corbet wrote:
>>>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>>>>
>>>>> Hi,
>>>>>
>>>>> Building htmldocs on docs-next currenly produces about 50 new warnings; which
>>>>> all of them are unexpected section title on DOC: kernel-doc directive, like:
>>>>>
>>>>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
>>>>>
>>>>> Userspace I/O
>>>>> ------------- [docutils]
>>>>> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
>>>>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.
>>>>
>>>> So I did not, and do not, see any of these errors; are you doing
>>>> something special to get them?
>>>
>>> Nope.
>>>
>>> I'm running my htmldocs builds on my Arch Linux system (with Sphinx 9.0.4 and
>>> Python 3.13.11).
>>>
>>> Full log (tarred up) attached.
>>>
>>> Thanks.
>>
>> Hi,
>> What docutils version, please?
> 
> Mine have:
> 
> docutils (Docutils 0.21.2, Python 3.13.11, on linux)

I'm using docutils-3.13 (Docutils 0.22.3, Python 3.13.11, on linux)
and I don't see these warnings.
Maybe it's something that has been fixed between 0.21.2 and 0.22.3... ?

-- 
~Randy

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2073 bytes --]

On Wed, Jan 07, 2026 at 04:21:40PM -0800, Randy Dunlap wrote:
> 
> 
> On 1/7/26 3:46 PM, Bagas Sanjaya wrote:
> > On Wed, Jan 07, 2026 at 10:19:32AM -0800, Randy Dunlap wrote:
> >>
> >>
> >> On 1/7/26 5:08 AM, Bagas Sanjaya wrote:
> >>> On Tue, Jan 06, 2026 at 02:58:43PM -0700, Jonathan Corbet wrote:
> >>>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> >>>>
> >>>>> Hi,
> >>>>>
> >>>>> Building htmldocs on docs-next currenly produces about 50 new warnings; which
> >>>>> all of them are unexpected section title on DOC: kernel-doc directive, like:
> >>>>>
> >>>>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: CRITICAL: Unexpected section title.
> >>>>>
> >>>>> Userspace I/O
> >>>>> ------------- [docutils]
> >>>>> WARNING: kernel-doc 'scripts/kernel-doc.py -rst -enable-lineno -function 'Userspace I/O' ./drivers/target/target_core_user.c' processing failed with: SystemMessage('/home/bagas/repo/linux-kernel/Documentation/driver-api/target:25: ./drivers/target/target_core_user.c:35: (SEVERE/4) Unexpected section title.\n\nUserspace I/O\n-------------')
> >>>>> /home/bagas/repo/linux-kernel/Documentation/driver-api/target:28: ./include/uapi/linux/target_core_user.h:14: CRITICAL: Unexpected section title.
> >>>>
> >>>> So I did not, and do not, see any of these errors; are you doing
> >>>> something special to get them?
> >>>
> >>> Nope.
> >>>
> >>> I'm running my htmldocs builds on my Arch Linux system (with Sphinx 9.0.4 and
> >>> Python 3.13.11).
> >>>
> >>> Full log (tarred up) attached.
> >>>
> >>> Thanks.
> >>
> >> Hi,
> >> What docutils version, please?
> > 
> > Mine have:
> > 
> > docutils (Docutils 0.21.2, Python 3.13.11, on linux)
> 
> I'm using docutils-3.13 (Docutils 0.22.3, Python 3.13.11, on linux)
> and I don't see these warnings.
> Maybe it's something that has been fixed between 0.21.2 and 0.22.3... ?

I get 100 warnings instead on docutils 0.22.4, unfortunately.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 270 bytes --]

On Wed, Jan 07, 2026 at 04:21:40PM -0800, Randy Dunlap wrote:
> I'm using docutils-3.13 (Docutils 0.22.3, Python 3.13.11, on linux)
> and I don't see these warnings.

What Sphinx version? Mine is 9.1.0.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [REGRESSION] Unexpected section title false positive warnings on DOC: directive

[Randy Dunlap]

On 1/13/26 7:03 PM, Bagas Sanjaya wrote:
> On Wed, Jan 07, 2026 at 04:21:40PM -0800, Randy Dunlap wrote:
>> I'm using docutils-3.13 (Docutils 0.22.3, Python 3.13.11, on linux)
>> and I don't see these warnings.
> 
> What Sphinx version? Mine is 9.1.0.
> 

I'm using 8.2.3.

-- 
~Randy