Re: [PATCH] Documentation: ext4: atomic_writes: Remove cross-reference labels

Jonathan Corbet
2025-06-12T12:22:21Z

"Darrick J. Wong" <djwong@kernel.org> writes:

>> > Sphinx wants to snarf up every .rst file it sees, regardless of whether
>> > it is explicitly made part of the document tree. So it will pick up
>> > atomic_writes.rst separately from the include.
>
> Does that mean that overview.rst doesn't need to include the other files
> at all?

Not quite. Sphinx does what is arguably the least useful thing possible
- it picks up and parses the file, but does not place it in the TOC
tree. It will normally warn in such cases, at least. So if this file
is not brought in with an "include" directive, it needs to appear in a
table of contents somewhere.

jon