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

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

[Bagas Sanjaya]

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.

Remove the labels to fix the warnings.

Fixes: 0bf1f51e34c4 ("ext4: Add atomic block write documentation")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/ext4/atomic_writes.rst | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/Documentation/filesystems/ext4/atomic_writes.rst b/Documentation/filesystems/ext4/atomic_writes.rst
index f65767df3620d5..f1a086aa026b1b 100644
--- a/Documentation/filesystems/ext4/atomic_writes.rst
+++ b/Documentation/filesystems/ext4/atomic_writes.rst
@@ -1,5 +1,4 @@
 .. SPDX-License-Identifier: GPL-2.0
-.. _atomic_writes:
 
 Atomic Block Writes
 -------------------------
@@ -154,7 +153,7 @@ Creating Filesystems with Atomic Write Support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 First check the atomic write units supported by block device.
-See :ref:`atomic_write_bdev_support` for more details.
+See "Hardware Support" section below for more details.
 
 For single-fsblock atomic writes with a larger block size
 (on systems with block size < page size):
@@ -201,7 +200,6 @@ details:
 The STATX_ATTR_WRITE_ATOMIC flag in ``statx->attributes`` is set if atomic
 writes are supported.
 
-.. _atomic_write_bdev_support:
 
 Hardware Support
 ----------------

base-commit: d3f825032091fc14c7d5e34bcd54317ae4246903
-- 
An old man doll... just what I always wanted! - Clara

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

[Darrick J. Wong]

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?

--D

> Remove the labels to fix the warnings.
> 
> Fixes: 0bf1f51e34c4 ("ext4: Add atomic block write documentation")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/filesystems/ext4/atomic_writes.rst | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)
> 
> diff --git a/Documentation/filesystems/ext4/atomic_writes.rst b/Documentation/filesystems/ext4/atomic_writes.rst
> index f65767df3620d5..f1a086aa026b1b 100644
> --- a/Documentation/filesystems/ext4/atomic_writes.rst
> +++ b/Documentation/filesystems/ext4/atomic_writes.rst
> @@ -1,5 +1,4 @@
>  .. SPDX-License-Identifier: GPL-2.0
> -.. _atomic_writes:
>  
>  Atomic Block Writes
>  -------------------------
> @@ -154,7 +153,7 @@ Creating Filesystems with Atomic Write Support
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
>  First check the atomic write units supported by block device.
> -See :ref:`atomic_write_bdev_support` for more details.
> +See "Hardware Support" section below for more details.
>  
>  For single-fsblock atomic writes with a larger block size
>  (on systems with block size < page size):
> @@ -201,7 +200,6 @@ details:
>  The STATX_ATTR_WRITE_ATOMIC flag in ``statx->attributes`` is set if atomic
>  writes are supported.
>  
> -.. _atomic_write_bdev_support:
>  
>  Hardware Support
>  ----------------
> 
> base-commit: d3f825032091fc14c7d5e34bcd54317ae4246903
> -- 
> An old man doll... just what I always wanted! - Clara
> 
> 

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

[Jonathan Corbet]

"Darrick J. Wong" <djwong@kernel.org> 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.

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.

jon

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

[Bagas Sanjaya]

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

On Wed, Jun 11, 2025 at 11:05:17AM -0600, Jonathan Corbet wrote:
> "Darrick J. Wong" <djwong@kernel.org> 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.
> 
> 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?

Confused...

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

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

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@kernel.org> 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

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

[Bagas Sanjaya]

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

On Wed, Jun 11, 2025 at 06:09:42PM -0700, Darrick J. Wong wrote:
> 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:
> > > 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?

I think overview.rst can be turned into toctree index.

> 
> > > 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?

OK then.

Thanks.

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

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

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

[Bagas Sanjaya]

On 6/12/25 09:48, Bagas Sanjaya wrote:
> On Wed, Jun 11, 2025 at 06:09:42PM -0700, Darrick J. Wong wrote:
>> 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:
>>>> 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?
> 
> I think overview.rst can be turned into toctree index.
> 

Or maybe slurp all included .rst's.

Thanks.


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

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

[Jonathan Corbet]

"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

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

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> So removing the labels looks good to you, right?
>
> Confused...

Removing unused labels is always good.  Removing *used* labels is
obviously a bit more questionable; in this case, as I said, it's
probably OK.

jon