[PATCH 0/5] ext4 docs toctree reorganization

[PATCH 0/5] ext4 docs toctree reorganization

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

Enjoy!

[1]: https://lore.kernel.org/linux-doc/20250618111544.22602-1-bagasdotme@gmail.com/
[2]: https://lore.kernel.org/linux-doc/87bjqjh5dr.fsf@trenco.lwn.net/

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
-- 
An old man doll... just what I always wanted! - Clara

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

[Bagas Sanjaya]

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")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
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/20250610091200.54075-2-bagasdotme@gmail.com/

 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(-)

diff --git a/Documentation/filesystems/ext4/dynamic.rst b/Documentation/filesystems/ext4/dynamic.rst
index bb0c84333341a5..bbad439aada262 100644
--- a/Documentation/filesystems/ext4/dynamic.rst
+++ b/Documentation/filesystems/ext4/dynamic.rst
@@ -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
diff --git a/Documentation/filesystems/ext4/globals.rst b/Documentation/filesystems/ext4/globals.rst
index b17418974fd35e..2264b76e873cc9 100644
--- a/Documentation/filesystems/ext4/globals.rst
+++ b/Documentation/filesystems/ext4/globals.rst
@@ -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
diff --git a/Documentation/filesystems/ext4/overview.rst b/Documentation/filesystems/ext4/overview.rst
index 9d4054c17ecb7b..171c3963d7f687 100644
--- a/Documentation/filesystems/ext4/overview.rst
+++ b/Documentation/filesystems/ext4/overview.rst
@@ -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
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/5] Documentation: ext4: Reduce toctree depth

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

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/ext4/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/filesystems/ext4/index.rst b/Documentation/filesystems/ext4/index.rst
index 705d813d558f0e..1ff8150c50e927 100644
--- a/Documentation/filesystems/ext4/index.rst
+++ b/Documentation/filesystems/ext4/index.rst
@@ -5,7 +5,7 @@ ext4 Data Structures and Algorithms
 ===================================
 
 .. toctree::
-   :maxdepth: 6
+   :maxdepth: 2
    :numbered:
 
    about
-- 
An old man doll... just what I always wanted! - Clara

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

[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")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/ext4/atomic_writes.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/filesystems/ext4/atomic_writes.rst b/Documentation/filesystems/ext4/atomic_writes.rst
index f65767df3620d5..aeb47ace738dfa 100644
--- a/Documentation/filesystems/ext4/atomic_writes.rst
+++ b/Documentation/filesystems/ext4/atomic_writes.rst
@@ -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
-- 
An old man doll... just what I always wanted! - Clara

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

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

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/ext4/blockgroup.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/filesystems/ext4/blockgroup.rst b/Documentation/filesystems/ext4/blockgroup.rst
index ed5a5cac6d40e1..7cbf0b2b778eab 100644
--- a/Documentation/filesystems/ext4/blockgroup.rst
+++ b/Documentation/filesystems/ext4/blockgroup.rst
@@ -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
-- 
An old man doll... just what I always wanted! - Clara

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

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

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 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

diff --git a/Documentation/filesystems/ext4/bitmaps.rst b/Documentation/filesystems/ext4/bitmaps.rst
index 91c45d86e9bb56..9d7d7b083a258c 100644
--- a/Documentation/filesystems/ext4/bitmaps.rst
+++ b/Documentation/filesystems/ext4/bitmaps.rst
@@ -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.
diff --git a/Documentation/filesystems/ext4/globals.rst b/Documentation/filesystems/ext4/globals.rst
index 2264b76e873cc9..c6a6abce818a17 100644
--- a/Documentation/filesystems/ext4/globals.rst
+++ b/Documentation/filesystems/ext4/globals.rst
@@ -11,6 +11,7 @@ have static metadata at fixed locations.
    super
    group_descr
    bitmaps
+   inode_table
    mmp
    journal
    orphan
diff --git a/Documentation/filesystems/ext4/inode_table.rst b/Documentation/filesystems/ext4/inode_table.rst
new file mode 100644
index 00000000000000..f7900a52c0d5da
--- /dev/null
+++ b/Documentation/filesystems/ext4/inode_table.rst
@@ -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.
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Bagas Sanjaya]

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

On Fri, Jun 20, 2025 at 05:56:39PM +0700, Bagas Sanjaya wrote:
> 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

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

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

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Darrick J. Wong]

On Mon, Jun 30, 2025 at 07:53:43AM +0700, Bagas Sanjaya wrote:
> On Fri, Jun 20, 2025 at 05:56:39PM +0700, Bagas Sanjaya wrote:
> > 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

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

Acked-by: "Darrick J. Wong" <djwong@kernel.org>

--D

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

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> 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

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Darrick J. Wong]

On Tue, Jul 01, 2025 at 01:11:25PM -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > 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.

I did, yesterday:
https://lore.kernel.org/linux-ext4/87y0t7rajm.fsf@trenco.lwn.net/T/#mc3ea7f04fc1b0e4294bce6bd60f5f605017f6f7c

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

--D

> Thanks,
> 
> jon
> 

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Jonathan Corbet]

"Darrick J. Wong" <djwong@kernel.org> writes:

> On Tue, Jul 01, 2025 at 01:11:25PM -0600, Jonathan Corbet wrote:
>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>> 
>> > 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.
>
> I did, yesterday:
> https://lore.kernel.org/linux-ext4/87y0t7rajm.fsf@trenco.lwn.net/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

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Theodore Ts'o]

On Tue, Jul 01, 2025 at 01:11:25PM -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > 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.

Acked-by: Theodore Ts'o <tytso@mit.edu>

						- Ted

Re: [PATCH 0/5] ext4 docs toctree reorganization

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> 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