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

[Darrick J. Wong]

On Thu, Jun 12, 2025 at 07:07:00AM +0700, Bagas Sanjaya wrote:
> On Wed, Jun 11, 2025 at 11:05:17AM -0600, Jonathan Corbet wrote:
> > "Darrick J. Wong" <djwong@xxxxxxxxxx> writes:
> > 
> > > On Tue, Jun 10, 2025 at 04:11:59PM +0700, Bagas Sanjaya wrote:
> > >> Sphinx reports htmldocs warnings on ext4 atomic block writes docs:
> > >> 
> > >> Documentation/filesystems/ext4/atomic_writes.rst:5: WARNING: duplicate label atomic_writes, other instance in Documentation/filesystems/ext4/atomic_writes.rst
> > >> Documentation/filesystems/ext4/atomic_writes.rst:207: WARNING: duplicate label atomic_write_bdev_support, other instance in Documentation/filesystems/ext4/atomic_writes.rst
> > >> 
> > >> These warnings reference duplicated cross-reference labels to themselves in
> > >> the same doc, which are because atomic_writes.rst is transcluded in
> > >> overview.rst via include:: directive, thus the culprit docs get processed
> > >> twice.
> > >
> > > <confused> How is that possible?  atomic_writes.rst is only "include::"d
> > > once in overview.rst.  Is the file implicitly included through some
> > > other means?
> > 
> > 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?

> > This could be "fixed" by removing the .rst extension from the included
> > file.  But, since there is no use of the atomic_writes label to begin
> > with, it's better to just take it out.  The other fix, removing a cross
> > reference, is not entirely ideal, but there is little text between the
> > label and the reference.
> 
> So removing the labels looks good to you, right?

I don't care that much either way, but if sphinx is going to include
every rst file implicitly then maybe we just get rid of the explicit
includes?

> Confused...

Me too.

--D

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