Skip to contentSkip to conversation

ext4 docs toctree reorganization

PATCH Applied Bagas Sanjaya 4 participants 13 messages Jun 20, 2025 – Jul 2, 2025

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

cover ext4 docs toctree reorganization

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

This patchset is based on docs-next tree.

Enjoy!

[1]: https://lore.kernel.org/linux-doc/[email protected]/
[2]: https://lore.kernel.org/linux-doc/[email protected]/

Bagas Sanjaya (5):
Documentation: ext4: Convert includes into toctrees
Documentation: ext4: Reduce toctree depth
Documentation: ext4: atomic_writes: Demote last three sections
Documentation: ext4: blockgroup: Add explicit title heading
Documentation: ext4: Move inode table short docs into its own file

 .../filesystems/ext4/atomic_writes.rst        | 10 ++++-----
 Documentation/filesystems/ext4/bitmaps.rst    |  7 ------
 Documentation/filesystems/ext4/blockgroup.rst | 11 ++++++----
 Documentation/filesystems/ext4/dynamic.rst    | 10 +++++----
 Documentation/filesystems/ext4/globals.rst    | 15 ++++++++-----
 Documentation/filesystems/ext4/index.rst      |  2 +-
 .../filesystems/ext4/inode_table.rst          |  9 ++++++++
 Documentation/filesystems/ext4/overview.rst   | 22 ++++++++++---------
 8 files changed, 49 insertions(+), 37 deletions(-)
 create mode 100644 Documentation/filesystems/ext4/inode_table.rst

base-commit: d3f825032091fc14c7d5e34bcd54317ae4246903

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH 1/5 Documentation: ext4: Convert includes into toctrees

ext4 docs are organized in three master docs (overview.rst, globals.rst, and dynamic.rst), in which these include other docs via include::
directive. These docs sturcture is better served by toctrees instead.

Convert the master docs to use toctrees.

Fixes 0bf1f51e34c4 ("ext4: Add atomic block write documentation")

---
This actually fixes duplicate label to itself warning as tried to be fixed in another approach [1], hence the Fixes: tag.

[1]: https://lore.kernel.org/linux-doc/[email protected]/

 Documentation/filesystems/ext4/dynamic.rst  | 10 ++++++----
 Documentation/filesystems/ext4/globals.rst  | 14 +++++++------
 Documentation/filesystems/ext4/overview.rst | 22 +++++++++++----------
 3 files changed, 26 insertions(+), 20 deletions(-)
Documentation/filesystems/ext4/dynamic.rst +6 -4
index bb0c84333341a5..bbad439aada262 100644
@@ -6,7 +6,9 @@ Dynamic Structures
 Dynamic metadata are created on the fly when files and blocks are
 allocated to files.
 
-.. include:: inodes.rst
-.. include:: ifork.rst
-.. include:: directory.rst
-.. include:: attributes.rst
+.. toctree::
+
+   inodes
+   ifork
+   directory
+   attributes
Documentation/filesystems/ext4/globals.rst +8 -6
index b17418974fd35e..2264b76e873cc9 100644
@@ -6,9 +6,11 @@ Global Structures
 The filesystem is sharded into a number of block groups, each of which
 have static metadata at fixed locations.
 
-.. include:: super.rst
-.. include:: group_descr.rst
-.. include:: bitmaps.rst
-.. include:: mmp.rst
-.. include:: journal.rst
-.. include:: orphan.rst
+.. toctree::
+
+   super
+   group_descr
+   bitmaps
+   mmp
+   journal
+   orphan
Documentation/filesystems/ext4/overview.rst +12 -10
index 9d4054c17ecb7b..171c3963d7f687 100644
@@ -16,13 +16,15 @@ All fields in ext4 are written to disk in little-endian order. HOWEVER,
 all fields in jbd2 (the journal) are written to disk in big-endian
 order.
 
-.. include:: blocks.rst
-.. include:: blockgroup.rst
-.. include:: special_inodes.rst
-.. include:: allocators.rst
-.. include:: checksums.rst
-.. include:: bigalloc.rst
-.. include:: inlinedata.rst
-.. include:: eainode.rst
-.. include:: verity.rst
-.. include:: atomic_writes.rst
+.. toctree::
+
+   blocks
+   blockgroup
+   special_inodes
+   allocators
+   checksums
+   bigalloc
+   inlinedata
+   eainode
+   verity
+   atomic_writes
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

PATCH 2/5 Documentation: ext4: Reduce toctree depth

In reply to Bagas Sanjaya

Reduce toctree depth from 6 to 2 to only show individual docs titles on top-level toctree (index.rst) and to not spoil the entire hierarchy.

---
 Documentation/filesystems/ext4/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/filesystems/ext4/index.rst +1 -1
index 705d813d558f0e..1ff8150c50e927 100644
@@ -5,7 +5,7 @@ ext4 Data Structures and Algorithms
 ===================================
 
 .. toctree::
-   :maxdepth: 6
+   :maxdepth: 2
    :numbered:
 
    about
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw

PATCH 3/5 Documentation: ext4: atomic_writes: Demote last three sections

In reply to Bagas Sanjaya

Last three sections of atomic block writes documentation are adorned as first-level title headings, which erroneously increase toctree entries in overview.rst. Demote them.

Fixes 0bf1f51e34c4 ("ext4: Add atomic block write documentation")
---
 Documentation/filesystems/ext4/atomic_writes.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/filesystems/ext4/atomic_writes.rst +5 -5
index f65767df3620d5..aeb47ace738dfa 100644
@@ -148,10 +148,10 @@ reserved during:
     only required to handle a split extent across leaf blocks.
 
 How to
-------
+~~~~~~
 
 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.
@@ -176,7 +176,7 @@ Where ``-b`` specifies the block size, ``-C`` specifies the cluster size in byte
 and ``-O bigalloc`` enables the bigalloc feature.
 
 Application Interface
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 Applications can use the ``pwritev2()`` system call with the ``RWF_ATOMIC`` flag
 to perform atomic writes:
@@ -204,7 +204,7 @@ writes are supported.
 .. _atomic_write_bdev_support:
 
 Hardware Support
-----------------
+~~~~~~~~~~~~~~~~
 
 The underlying storage device must support atomic write operations.
 Modern NVMe and SCSI devices often provide this capability.
@@ -217,7 +217,7 @@ Nonzero values for these attributes indicate that the device supports
 atomic writes.
 
 See Also
---------
+~~~~~~~~
 
 * :doc:`bigalloc` - Documentation on the bigalloc feature
 * :doc:`allocators` - Documentation on block allocation in ext4
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw

PATCH 4/5 Documentation: ext4: blockgroup: Add explicit title heading

In reply to Bagas Sanjaya

Block groups documentation has three, first-level section headings. These headings' text become toctree entries and the first one "Layout" becomes docs title in the output, which isn't conveying the docs contents.

Add explicit title heading and demote the rest.

---
 Documentation/filesystems/ext4/blockgroup.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)
Documentation/filesystems/ext4/blockgroup.rst +7 -4
index ed5a5cac6d40e1..7cbf0b2b778eab 100644
@@ -1,7 +1,10 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+Block Groups
+------------
+
 Layout
-------
+~~~~~~
 
 The layout of a standard block group is approximately as follows (each
 of these fields is discussed in a separate section below):
@@ -60,7 +63,7 @@ groups (flex_bg). Leftover space is used for file data blocks, indirect
 block maps, extent tree blocks, and extended attributes.
 
 Flexible Block Groups
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 Starting in ext4, there is a new feature called flexible block groups
 (flex_bg). In a flex_bg, several block groups are tied together as one
@@ -78,7 +81,7 @@ if flex_bg is enabled. The number of block groups that make up a
 flex_bg is given by 2 ^ ``sb.s_log_groups_per_flex``.
 
 Meta Block Groups
------------------
+~~~~~~~~~~~~~~~~~
 
 Without the option META_BG, for safety concerns, all block group
 descriptors copies are kept in the first block group. Given the default
@@ -117,7 +120,7 @@ Please see an important note about ``BLOCK_UNINIT`` in the section about
 block and inode bitmaps.
 
 Lazy Block Group Initialization
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A new feature for ext4 are three block group descriptor flags that
 enable mkfs to skip initializing other parts of the block group
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#5 lore raw

PATCH 5/5 Documentation: ext4: Move inode table short docs into its own file

In reply to Bagas Sanjaya

The short description of inode table is in bitmaps.rst alongside the proper bitmpas documentation. The docs file is short enough that it fits whole browser screen on desktop, which implies that when readers click "Inode Table", they will essentially see bitmaps docs.

Move inode table short description.

---
 Documentation/filesystems/ext4/bitmaps.rst     | 7 -------
 Documentation/filesystems/ext4/globals.rst     | 1 +
 Documentation/filesystems/ext4/inode_table.rst | 9 +++++++++
 3 files changed, 10 insertions(+), 7 deletions(-)
 create mode 100644 Documentation/filesystems/ext4/inode_table.rst
Documentation/filesystems/ext4/bitmaps.rst +0 -7
index 91c45d86e9bb56..9d7d7b083a258c 100644
@@ -19,10 +19,3 @@ necessarily the case that no blocks are in use -- if ``meta_bg`` is set,
 the bitmaps and group descriptor live inside the group. Unfortunately,
 ext2fs_test_block_bitmap2() will return '0' for those locations,
 which produces confusing debugfs output.
-
-Inode Table
------------
-Inode tables are statically allocated at mkfs time.  Each block group
-descriptor points to the start of the table, and the superblock records
-the number of inodes per group.  See the section on inodes for more
-information.
Documentation/filesystems/ext4/globals.rst +1 -0
index 2264b76e873cc9..c6a6abce818a17 100644
@@ -11,6 +11,7 @@ have static metadata at fixed locations.
    super
    group_descr
    bitmaps
+   inode_table
    mmp
    journal
    orphan
Documentation/filesystems/ext4/inode_table.rst new file +9 -0
new file mode 100644
index 00000000000000..f7900a52c0d5da
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Inode Table
+-----------
+
+Inode tables are statically allocated at mkfs time.  Each block group
+descriptor points to the start of the table, and the superblock records
+the number of inodes per group.  See :doc:`inode documentation <inodes>`
+for more information on inode table layout.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#6 lore raw
In reply to Bagas Sanjaya
Quoted 10 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

review ping

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#7 lore raw
Quoted 8 lines · Bagas Sanjaya
Quoted 7 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Quoted 5 lines
Quoted 3 lines

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

review ping

This sounds a lot better than dumping everything into a single huge rst file. :)

The structural changes to the documents look ok to me, though I'm no rst expert so I trust you built the documentation and it didn't spawn DOOM II or anything... ;)

--D

Quoted 3 lines
Signature · 2 lines
-- 
An old man doll... just what I always wanted! - Clara
maintainer
#8 lore raw
In reply to Bagas Sanjaya
Quoted 11 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

This patchset is based on docs-next tree.

So to me this seems like an improvement. I'm happy to take it, though would prefer an ack from ext4land if possible.

Thanks,

jon

#9 lore raw
Quoted 9 lines · Jonathan Corbet
Quoted 7 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Quoted 7 lines
Quoted 4 lines

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

This patchset is based on docs-next tree.

So to me this seems like an improvement. I'm happy to take it, though would prefer an ack from ext4land if possible.

I did, yesterday:
https://lore.kernel.org/linux-ext4/[email protected]/T/#mc3ea7f04fc1b0e4294bce6bd60f5f605017f6f7c

Though I'm also happy not to be thought of as part of 'ext4land' ;)

--D

Quoted 4 lines

Thanks,

jon

maintainer
#10 lore raw
Quoted 15 lines · Darrick J. Wong
Quoted 14 lines · Jonathan Corbet
Quoted 11 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

This patchset is based on docs-next tree.

Quoted 7 lines
Quoted 2 lines

So to me this seems like an improvement. I'm happy to take it, though would prefer an ack from ext4land if possible.

I did, yesterday:
https://lore.kernel.org/linux-ext4/[email protected]/T/#mc3ea7f04fc1b0e4294bce6bd60f5f605017f6f7c

Though I'm also happy not to be thought of as part of 'ext4land' ;)

Yup, I have your ack ... if that's good enough I'll proceed. You can be from wherever you want as far as I'm concerned :)

Thanks,

jon

maintainer Acked-by
#11 lore raw
In reply to Jonathan Corbet
Quoted 9 lines · Jonathan Corbet
Quoted 7 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Quoted 7 lines
Quoted 4 lines

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

This patchset is based on docs-next tree.

So to me this seems like an improvement. I'm happy to take it, though would prefer an ack from ext4land if possible.

- Ted

maintainer Applied
#12 lore raw
In reply to Bagas Sanjaya
Quoted 11 lines · Bagas Sanjaya

Hi Jon, hi Ted,

While discussing on my previous ext4 docs reorganization attempt by merging contents [1], Jon suggested that considering current docs file structure, a proper toctree would be ideal [2]. So, here's the patchset that does exactly that.

Actual conversion to toctree structure is in [1/5], while the rest is cleanups to make the resulting toctree nicer.

This patchset is based on docs-next tree.

Applied, thanks.

jon