ext4 docs toctree reorganization
Subsystems (2)
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
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.
---
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
@@ -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
@@ -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
@@ -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
PATCH 2/5 Documentation: ext4: Reduce toctree depth
In reply to Bagas SanjayaReduce 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
@@ -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
PATCH 3/5 Documentation: ext4: atomic_writes: Demote last three sections
In reply to Bagas SanjayaLast three sections of atomic block writes documentation are adorned as first-level title headings, which erroneously increase toctree entries in overview.rst. Demote them.
--- Documentation/filesystems/ext4/atomic_writes.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/filesystems/ext4/atomic_writes.rst +5 -5
@@ -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
PATCH 4/5 Documentation: ext4: blockgroup: Add explicit title heading
In reply to Bagas SanjayaBlock 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
@@ -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
PATCH 5/5 Documentation: ext4: Move inode table short docs into its own file
In reply to Bagas SanjayaThe 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
@@ -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
@@ -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
@@ -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
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
Darrick J. Wong
Acked-byQuoted 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
Jonathan Corbet
maintainerQuoted 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
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
Jonathan Corbet
maintainerQuoted 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/#mc3ea7f04fc1b0e4294bce6bd60f5f605017f6f7cThough 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
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
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