Skip to contentSkip to conversation

Documentation: ext4: atomic_writes: Remove cross-reference labels

PATCH In review Bagas Sanjaya 3 participants 9 messages Jun 10, 2025 – Jun 12, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: ext4: atomic_writes: Remove cross-reference labels

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")
---
 Documentation/filesystems/ext4/atomic_writes.rst | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
Documentation/filesystems/ext4/atomic_writes.rst +1 -3
index f65767df3620d5..f1a086aa026b1b 100644
@@ -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

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw
Quoted 9 lines · 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.

<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

Quoted 41 lines

Remove the labels to fix the warnings.

Fixes 0bf1f51e34c4 ("ext4: Add atomic block write documentation")
---
 Documentation/filesystems/ext4/atomic_writes.rst | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)
Documentation/filesystems/ext4/atomic_writes.rst +1 -3
index f65767df3620d5..f1a086aa026b1b 100644
@@ -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

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#2 lore raw
Quoted 6 lines · Darrick J. Wong
Quoted 5 lines · 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

Quoted 8 lines
Quoted 4 lines

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

#3 lore raw
Quoted 21 lines · Jonathan Corbet
Quoted 6 lines · Darrick J. Wong
Quoted 5 lines · 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

Quoted 8 lines
Quoted 4 lines

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.

Quoted 5 lines

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

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw
Quoted 14 lines · Bagas Sanjaya
Quoted 13 lines · Jonathan Corbet
Quoted 11 lines · Darrick J. Wong
Quoted 9 lines · 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.

Quoted 7 lines
Quoted 7 lines
Quoted 3 lines

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

Quoted 7 lines
Quoted 5 lines

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?

Quoted 1 line

Confused...

Me too.

--D

Quoted 3 lines
Signature · 2 lines
-- 
An old man doll... just what I always wanted! - Clara
#5 lore raw
Quoted 8 lines · Darrick J. Wong
Quoted 4 lines · Bagas Sanjaya
Quoted 3 lines · Jonathan Corbet

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.

Quoted 7 lines
Quoted 7 lines
Quoted 6 lines

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.

Quoted 5 lines
Quoted 1 line

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.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#6 lore raw
Quoted 12 lines · Bagas Sanjaya
Quoted 8 lines · Darrick J. Wong
Quoted 4 lines · Bagas Sanjaya
Quoted 3 lines · Jonathan Corbet

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.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#7 lore raw
In reply to Darrick J. Wong
Quoted 6 lines · Darrick J. Wong
Quoted 3 lines
Quoted 3 lines

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

maintainer
#8 lore raw
In reply to Bagas Sanjaya
Quoted 3 lines · Bagas Sanjaya

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