Documentation: ext4: atomic_writes: Remove cross-reference labels
Subsystems (2)
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.
--- Documentation/filesystems/ext4/atomic_writes.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-)
Documentation/filesystems/ext4/atomic_writes.rst +1 -3
@@ -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
Quoted 9 lines · Bagas Sanjaya
Sphinx reports htmldocs warnings on ext4 atomic block writes docs:
Documentation/filesystems/ext4/atomic_writes.rst:5: WARNING: duplicate labelatomic_writes, other instance inDocumentation/filesystems/ext4/atomic_writes.rstDocumentation/filesystems/ext4/atomic_writes.rst:207: WARNING: duplicate labelatomic_write_bdev_support, other instance inDocumentation/filesystems/ext4/atomic_writes.rstThese warnings reference duplicated cross-reference labels to themselves in the same doc, which are because
atomic_writes.rstis transcluded inoverview.rstvia 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")Signed-off-by Bagas Sanjaya <[email protected]>--- Documentation/filesystems/ext4/atomic_writes.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-)Documentation/filesystems/ext4/atomic_writes.rst +1
-3@@ -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:
d3f825032091fc14c7d5e34bcd54317ae4246903Signature · 1 line
An old man doll... just what I always wanted! - Clara
Jonathan Corbet
maintainerQuoted 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 labelatomic_writes, other instance inDocumentation/filesystems/ext4/atomic_writes.rstDocumentation/filesystems/ext4/atomic_writes.rst:207: WARNING: duplicate labelatomic_write_bdev_support, other instance inDocumentation/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.rstis transcluded inoverview.rstvia include:: directive, thus the culprit docs get processed twice.<confused> How is that possible?
atomic_writes.rstis only "include::"d once inoverview.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
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 labelatomic_writes, other instance inDocumentation/filesystems/ext4/atomic_writes.rstDocumentation/filesystems/ext4/atomic_writes.rst:207: WARNING: duplicate labelatomic_write_bdev_support, other instance inDocumentation/filesystems/ext4/atomic_writes.rstQuoted 8 lines
Quoted 4 lines
These warnings reference duplicated cross-reference labels to themselves in the same doc, which are because
atomic_writes.rstis transcluded inoverview.rstvia include:: directive, thus the culprit docs get processed twice.<confused> How is that possible?
atomic_writes.rstis only "include::"d once inoverview.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.rstseparately 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_writeslabel 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
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 labelatomic_writes, other instance inDocumentation/filesystems/ext4/atomic_writes.rstDocumentation/filesystems/ext4/atomic_writes.rst:207: WARNING: duplicate labelatomic_write_bdev_support, other instance inDocumentation/filesystems/ext4/atomic_writes.rstThese warnings reference duplicated cross-reference labels to themselves in the same doc, which are because
atomic_writes.rstis transcluded inoverview.rstvia 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.rstis only "include::"d once inoverview.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.rstseparately 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_writeslabel 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
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.rstseparately from the include.Does that mean that
overview.rstdoesn'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_writeslabel 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
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.rstseparately from the include.Does that mean that
overview.rstdoesn't need to include the other files at all?I think
overview.rstcan 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
Jonathan Corbet
maintainerQuoted 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.rstseparately from the include.Does that mean that
overview.rstdoesn'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
Jonathan Corbet
maintainerQuoted 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