Slurp (squash) ext4 subdocs
Subsystems (2)
cover Slurp (squash) ext4 subdocs
When a doc is included by other doc via include:: directive, Sphinx will pick the included doc and parse it independently from the including doc regardless if it is listed in the docs toctree. This, however, can exposes duplicate label warning that refers the label to itself (bug?) when the label is placed before any section heading, since Sphinx encounters the label twice, both when parsing the included and the including docs.
This could be solved by removing the problematic label. However, when it is heavily referenced by other doc (e.g. via :ref: directive), this can be a churn. Furthermore, the include:: usage pattern in kernel docs is to use it to included a common doc part that is shared by many docs (e.g. isonum.txt). ext4 docs, though, is the opposite: splitting docs into multiple reST files (subdocs) and including them in three master docs (overview.rst, globals.rst, and dynamic.rst)
Let's slurp (squash) the subdocs instead. This will make the master docs larger of course (although not as big as KVM API docs), but one can use cross-reference labels without hitting aforementioned warning bug. Also, docs directory structure is tidier with only 4 files (master docs and about.rst). As a bonus, also reduce toctree depth as to not spill the whole hierarchy.
This patchset is an alternative to the fixup patch that is actually removing the offending atomic_writes labels ([1]).
[1]: https://lore.kernel.org/linux-doc/[email protected]/
Bagas Sanjaya (4):
Documentation: ext4: Slurp included subdocs in high-level overview
docs
Documentation: ext4: Slurp included subdocs in global structures docs
Documentation: ext4: Slurp included subdocs in dynamic structures docs
Documentation: ext4: Reduce toctree depth
Documentation/filesystems/ext4/allocators.rst | 56 - .../filesystems/ext4/atomic_writes.rst | 225 -- Documentation/filesystems/ext4/attributes.rst | 191 -- Documentation/filesystems/ext4/bigalloc.rst | 34 - Documentation/filesystems/ext4/bitmaps.rst | 28 - Documentation/filesystems/ext4/blockgroup.rst | 135 -- Documentation/filesystems/ext4/blocks.rst | 144 -- Documentation/filesystems/ext4/checksums.rst | 73 - Documentation/filesystems/ext4/directory.rst | 453 ---- Documentation/filesystems/ext4/dynamic.rst | 1415 +++++++++++- Documentation/filesystems/ext4/eainode.rst | 18 - Documentation/filesystems/ext4/globals.rst | 1923 ++++++++++++++++- .../filesystems/ext4/group_descr.rst | 173 -- Documentation/filesystems/ext4/ifork.rst | 194 -- Documentation/filesystems/ext4/index.rst | 2 +- Documentation/filesystems/ext4/inlinedata.rst | 37 - Documentation/filesystems/ext4/inodes.rst | 578 ----- Documentation/filesystems/ext4/journal.rst | 761 ------- Documentation/filesystems/ext4/mmp.rst | 77 - Documentation/filesystems/ext4/orphan.rst | 42 - Documentation/filesystems/ext4/overview.rst | 819 ++++++- .../filesystems/ext4/special_inodes.rst | 55 - Documentation/filesystems/ext4/super.rst | 839 ------- Documentation/filesystems/ext4/verity.rst | 44 - 24 files changed, 4138 insertions(+), 4178 deletions(-) delete mode 100644 Documentation/filesystems/ext4/allocators.rst delete mode 100644 Documentation/filesystems/ext4/atomic_writes.rst delete mode 100644 Documentation/filesystems/ext4/attributes.rst delete mode 100644 Documentation/filesystems/ext4/bigalloc.rst delete mode 100644 Documentation/filesystems/ext4/bitmaps.rst delete mode 100644 Documentation/filesystems/ext4/blockgroup.rst delete mode 100644 Documentation/filesystems/ext4/blocks.rst delete mode 100644 Documentation/filesystems/ext4/checksums.rst delete mode 100644 Documentation/filesystems/ext4/directory.rst delete mode 100644 Documentation/filesystems/ext4/eainode.rst delete mode 100644 Documentation/filesystems/ext4/group_descr.rst delete mode 100644 Documentation/filesystems/ext4/ifork.rst delete mode 100644 Documentation/filesystems/ext4/inlinedata.rst delete mode 100644 Documentation/filesystems/ext4/inodes.rst delete mode 100644 Documentation/filesystems/ext4/journal.rst delete mode 100644 Documentation/filesystems/ext4/mmp.rst delete mode 100644 Documentation/filesystems/ext4/orphan.rst delete mode 100644 Documentation/filesystems/ext4/special_inodes.rst delete mode 100644 Documentation/filesystems/ext4/super.rst delete mode 100644 Documentation/filesystems/ext4/verity.rst
base-commit: d3f825032091fc14c7d5e34bcd54317ae4246903
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 1/4 Documentation: ext4: Slurp included subdocs in high-level overview docs
Slurp subdocumentations for high-level ext4 design overview (overview.rst) by replacing reST include:: directive with their respective contents.
--- Documentation/filesystems/ext4/allocators.rst | 56 -- .../filesystems/ext4/atomic_writes.rst | 225 ----- Documentation/filesystems/ext4/bigalloc.rst | 34 - Documentation/filesystems/ext4/blockgroup.rst | 135 --- Documentation/filesystems/ext4/blocks.rst | 144 --- Documentation/filesystems/ext4/checksums.rst | 73 -- Documentation/filesystems/ext4/eainode.rst | 18 - Documentation/filesystems/ext4/inlinedata.rst | 37 - Documentation/filesystems/ext4/overview.rst | 819 +++++++++++++++++- .../filesystems/ext4/special_inodes.rst | 55 -- Documentation/filesystems/ext4/verity.rst | 44 - 11 files changed, 809 insertions(+), 831 deletions(-) delete mode 100644 Documentation/filesystems/ext4/allocators.rst delete mode 100644 Documentation/filesystems/ext4/atomic_writes.rst delete mode 100644 Documentation/filesystems/ext4/bigalloc.rst delete mode 100644 Documentation/filesystems/ext4/blockgroup.rst delete mode 100644 Documentation/filesystems/ext4/blocks.rst delete mode 100644 Documentation/filesystems/ext4/checksums.rst delete mode 100644 Documentation/filesystems/ext4/eainode.rst delete mode 100644 Documentation/filesystems/ext4/inlinedata.rst delete mode 100644 Documentation/filesystems/ext4/special_inodes.rst delete mode 100644 Documentation/filesystems/ext4/verity.rst
Documentation/filesystems/ext4/allocators.rst deleted +0 -56
@@ -1,56 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Block and Inode Allocation Policy ---------------------------------- - -ext4 recognizes (better than ext3, anyway) that data locality is -generally a desirably quality of a filesystem. On a spinning disk, -keeping related blocks near each other reduces the amount of movement -that the head actuator and disk must perform to access a data block, -thus speeding up disk IO. On an SSD there of course are no moving parts, -but locality can increase the size of each transfer request while -reducing the total number of requests. This locality may also have the -effect of concentrating writes on a single erase block, which can speed -up file rewrites significantly. Therefore, it is useful to reduce -fragmentation whenever possible. - -The first tool that ext4 uses to combat fragmentation is the multi-block -allocator. When a file is first created, the block allocator -speculatively allocates 8KiB of disk space to the file on the assumption -that the space will get written soon. When the file is closed, the -unused speculative allocations are of course freed, but if the -speculation is correct (typically the case for full writes of small -files) then the file data gets written out in a single multi-block -extent. A second related trick that ext4 uses is delayed allocation. -Under this scheme, when a file needs more blocks to absorb file writes, -the filesystem defers deciding the exact placement on the disk until all -the dirty buffers are being written out to disk. By not committing to a -particular placement until it's absolutely necessary (the commit timeout -is hit, or sync() is called, or the kernel runs out of memory), the hope -is that the filesystem can make better location decisions. - -The third trick that ext4 (and ext3) uses is that it tries to keep a -file's data blocks in the same block group as its inode. This cuts down -on the seek penalty when the filesystem first has to read a file's inode -to learn where the file's data blocks live and then seek over to the -file's data blocks to begin I/O operations. - -The fourth trick is that all the inodes in a directory are placed in the -same block group as the directory, when feasible. The working assumption -here is that all the files in a directory might be related, therefore it -is useful to try to keep them all together. - -The fifth trick is that the disk volume is cut up into 128MB block -groups; these mini-containers are used as outlined above to try to -maintain data locality. However, there is a deliberate quirk -- when a -directory is created in the root directory, the inode allocator scans -the block groups and puts that directory into the least heavily loaded -block group that it can find. This encourages directories to spread out -over a disk; as the top-level directory/file blobs fill up one block -group, the allocators simply move on to the next block group. Allegedly -this scheme evens out the loading on the block groups, though the author -suspects that the directories which are so unlucky as to land towards -the end of a spinning drive get a raw deal performance-wise. - -Of course if all of these mechanisms fail, one can always use e4defrag -to defragment files.
Documentation/filesystems/ext4/atomic_writes.rst deleted +0 -225
225 lines not on this page · raw message
Documentation/filesystems/ext4/bigalloc.rst deleted +0 -34
@@ -1,34 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Bigalloc --------- - -At the moment, the default size of a block is 4KiB, which is a commonly -supported page size on most MMU-capable hardware. This is fortunate, as -ext4 code is not prepared to handle the case where the block size -exceeds the page size. However, for a filesystem of mostly huge files, -it is desirable to be able to allocate disk blocks in units of multiple -blocks to reduce both fragmentation and metadata overhead. The -bigalloc feature provides exactly this ability. - -The bigalloc feature (EXT4_FEATURE_RO_COMPAT_BIGALLOC) changes ext4 to -use clustered allocation, so that each bit in the ext4 block allocation -bitmap addresses a power of two number of blocks. For example, if the -file system is mainly going to be storing large files in the 4-32 -megabyte range, it might make sense to set a cluster size of 1 megabyte. -This means that each bit in the block allocation bitmap now addresses -256 4k blocks. This shrinks the total size of the block allocation -bitmaps for a 2T file system from 64 megabytes to 256 kilobytes. It also -means that a block group addresses 32 gigabytes instead of 128 megabytes, -also shrinking the amount of file system overhead for metadata. - -The administrator can set a block cluster size at mkfs time (which is -stored in the s_log_cluster_size field in the superblock); from then -on, the block bitmaps track clusters, not individual blocks. This means -that block groups can be several gigabytes in size (instead of just -128MiB); however, the minimum allocation unit becomes a cluster, not a -block, even for directories. TaoBao had a patchset to extend the “use -units of clusters instead of blocks” to the extent tree, though it is -not clear where those patches went-- they eventually morphed into -“extent tree v2” but that code has not landed as of May 2015. -
Documentation/filesystems/ext4/blockgroup.rst deleted +0 -135
135 lines not on this page · raw message
Documentation/filesystems/ext4/blocks.rst deleted +0 -144
144 lines not on this page · raw message
Documentation/filesystems/ext4/checksums.rst deleted +0 -73
73 lines not on this page · raw message
Documentation/filesystems/ext4/eainode.rst deleted +0 -18
@@ -1,18 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Large Extended Attribute Values -------------------------------- - -To enable ext4 to store extended attribute values that do not fit in the -inode or in the single extended attribute block attached to an inode, -the EA_INODE feature allows us to store the value in the data blocks of -a regular file inode. This “EA inode” is linked only from the extended -attribute name index and must not appear in a directory entry. The -inode's i_atime field is used to store a checksum of the xattr value; -and i_ctime/i_version store a 64-bit reference count, which enables -sharing of large xattr values between multiple owning inodes. For -backward compatibility with older versions of this feature, the -i_mtime/i_generation *may* store a back-reference to the inode number -and i_generation of the **one** owning inode (in cases where the EA -inode is not referenced by multiple inodes) to verify that the EA inode -is the correct one being accessed.
Documentation/filesystems/ext4/inlinedata.rst deleted +0 -37
@@ -1,37 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Inline Data ------------ - -The inline data feature was designed to handle the case that a file's -data is so tiny that it readily fits inside the inode, which -(theoretically) reduces disk block consumption and reduces seeks. If the -file is smaller than 60 bytes, then the data are stored inline in -``inode.i_block``. If the rest of the file would fit inside the extended -attribute space, then it might be found as an extended attribute -“system.data” within the inode body (“ibody EA”). This of course -constrains the amount of extended attributes one can attach to an inode. -If the data size increases beyond i_block + ibody EA, a regular block -is allocated and the contents moved to that block. - -Pending a change to compact the extended attribute key used to store -inline data, one ought to be able to store 160 bytes of data in a -256-byte inode (as of June 2015, when i_extra_isize is 28). Prior to -that, the limit was 156 bytes due to inefficient use of inode space. - -The inline data feature requires the presence of an extended attribute -for “system.data”, even if the attribute value is zero length. - -Inline Directories -~~~~~~~~~~~~~~~~~~ - -The first four bytes of i_block are the inode number of the parent -directory. Following that is a 56-byte space for an array of directory -entries; see ``struct ext4_dir_entry``. If there is a “system.data” -attribute in the inode body, the EA value is an array of -``struct ext4_dir_entry`` as well. Note that for inline directories, the -i_block and EA space are treated as separate dirent blocks; directory -entries cannot span the two. - -Inline directory entries are not checksummed, as the inode checksum -should protect all inline data contents.
Documentation/filesystems/ext4/overview.rst +809 -10
822 lines not on this page · raw message
Documentation/filesystems/ext4/special_inodes.rst deleted +0 -55
55 lines not on this page · raw message
Documentation/filesystems/ext4/verity.rst deleted +0 -44
44 lines not on this page · raw message
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 2/4 Documentation: ext4: Slurp included subdocs in global structures docs
In reply to Bagas SanjayaSlurp subdocumentations for global structures (globals.rst) by replacing reST include:: directive with their respective contents.
--- Documentation/filesystems/ext4/bitmaps.rst | 28 - Documentation/filesystems/ext4/globals.rst | 1923 ++++++++++++++++- .../filesystems/ext4/group_descr.rst | 173 -- Documentation/filesystems/ext4/journal.rst | 761 ------- Documentation/filesystems/ext4/mmp.rst | 77 - Documentation/filesystems/ext4/orphan.rst | 42 - Documentation/filesystems/ext4/super.rst | 839 ------- 7 files changed, 1917 insertions(+), 1926 deletions(-) delete mode 100644 Documentation/filesystems/ext4/bitmaps.rst delete mode 100644 Documentation/filesystems/ext4/group_descr.rst delete mode 100644 Documentation/filesystems/ext4/journal.rst delete mode 100644 Documentation/filesystems/ext4/mmp.rst delete mode 100644 Documentation/filesystems/ext4/orphan.rst delete mode 100644 Documentation/filesystems/ext4/super.rst
Documentation/filesystems/ext4/bitmaps.rst deleted +0 -28
@@ -1,28 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Block and inode Bitmaps ------------------------ - -The data block bitmap tracks the usage of data blocks within the block -group. - -The inode bitmap records which entries in the inode table are in use. - -As with most bitmaps, one bit represents the usage status of one data -block or inode table entry. This implies a block group size of 8 * -number_of_bytes_in_a_logical_block. - -NOTE: If ``BLOCK_UNINIT`` is set for a given block group, various parts -of the kernel and e2fsprogs code pretends that the block bitmap contains -zeros (i.e. all blocks in the group are free). However, it is not -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 +1917 -6
1,926 lines not on this page · raw message
Documentation/filesystems/ext4/group_descr.rst deleted +0 -173
173 lines not on this page · raw message
Documentation/filesystems/ext4/journal.rst deleted +0 -761
761 lines not on this page · raw message
Documentation/filesystems/ext4/mmp.rst deleted +0 -77
77 lines not on this page · raw message
Documentation/filesystems/ext4/orphan.rst deleted +0 -42
35 lines not on this page · raw message
Documentation/filesystems/ext4/super.rst deleted +0 -839
839 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Part of the diff is not shown here. View the raw message.
PATCH 3/4 Documentation: ext4: Slurp included subdocs in dynamic structures docs
In reply to Bagas SanjayaSlurp subdocumentations for dynamic structures (dynamic.rst) by replacing reST include:: directive with their respective contents.
--- Documentation/filesystems/ext4/attributes.rst | 191 --- Documentation/filesystems/ext4/directory.rst | 453 ------ Documentation/filesystems/ext4/dynamic.rst | 1415 ++++++++++++++++- Documentation/filesystems/ext4/ifork.rst | 194 --- Documentation/filesystems/ext4/inodes.rst | 578 ------- 5 files changed, 1411 insertions(+), 1420 deletions(-) delete mode 100644 Documentation/filesystems/ext4/attributes.rst delete mode 100644 Documentation/filesystems/ext4/directory.rst delete mode 100644 Documentation/filesystems/ext4/ifork.rst delete mode 100644 Documentation/filesystems/ext4/inodes.rst
Documentation/filesystems/ext4/attributes.rst deleted +0 -191
@@ -1,191 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Extended Attributes -------------------- - -Extended attributes (xattrs) are typically stored in a separate data -block on the disk and referenced from inodes via ``inode.i_file_acl*``. -The first use of extended attributes seems to have been for storing file -ACLs and other security data (selinux). With the ``user_xattr`` mount -option it is possible for users to store extended attributes so long as -all attribute names begin with “user”; this restriction seems to have -disappeared as of Linux 3.0. - -There are two places where extended attributes can be found. The first -place is between the end of each inode entry and the beginning of the -next inode entry. For example, if inode.i_extra_isize = 28 and -sb.inode_size = 256, then there are 256 - (128 + 28) = 100 bytes -available for in-inode extended attribute storage. The second place -where extended attributes can be found is in the block pointed to by -``inode.i_file_acl``. As of Linux 3.11, it is not possible for this -block to contain a pointer to a second extended attribute block (or even -the remaining blocks of a cluster). In theory it is possible for each -attribute's value to be stored in a separate data block, though as of -Linux 3.11 the code does not permit this. - -Keys are generally assumed to be ASCIIZ strings, whereas values can be -strings or binary data. - -Extended attributes, when stored after the inode, have a header -``ext4_xattr_ibody_header`` that is 4 bytes long: - -.. list-table:: - :widths: 8 8 24 40 - :header-rows: 1 - - * - Offset - - Type - - Name - - Description - * - 0x0 - - __le32 - - h_magic - - Magic number for identification, 0xEA020000. This value is set by the - Linux driver, though e2fsprogs doesn't seem to check it(?) - -The beginning of an extended attribute block is in -``struct ext4_xattr_header``, which is 32 bytes long: - -.. list-table:: - :widths: 8 8 24 40 - :header-rows: 1 - - * - Offset - - Type - - Name - - Description - * - 0x0 - - __le32 - - h_magic - - Magic number for identification, 0xEA020000. - * - 0x4 - - __le32 - - h_refcount - - Reference count. - * - 0x8 - - __le32 - - h_blocks - - Number of disk blocks used. - * - 0xC - - __le32 - - h_hash - - Hash value of all attributes. - * - 0x10 - - __le32 - - h_checksum - - Checksum of the extended attribute block. - * - 0x14 - - __u32 - - h_reserved[3] - - Zero. - -The checksum is calculated against the FS UUID, the 64-bit block number -of the extended attribute block, and the entire block (header + -entries). - -Following the ``struct ext4_xattr_header`` or -``struct ext4_xattr_ibody_header`` is an array of -``struct ext4_xattr_entry``; each of these entries is at least 16 bytes -long. When stored in an external block, the ``struct ext4_xattr_entry`` -entries must be stored in sorted order. The sort order is -``e_name_index``, then ``e_name_len``, and finally ``e_name``. -Attributes stored inside an inode do not need be stored in sorted order. - -.. list-table:: - :widths: 8 8 24 40 - :header-rows: 1 - - * - Offset - - Type - - Name - - Description - * - 0x0 - - __u8 - - e_name_len - - Length of name. - * - 0x1 - - __u8 - - e_name_index - - Attribute name index. There is a discussion of this below. - * - 0x2 - - __le16 - - e_value_offs - - Location of this attribute's value on the disk block where it is stored. - Multiple attributes can share the same value. For an inode attribute - this value is relative to the start of the first entry; for a block this - value is relative to the start of the block (i.e. the header). - * - 0x4 - - __le32 - - e_value_inum - - The inode where the value is stored. Zero indicates the value is in the - same block as this entry. This field is only used if the - INCOMPAT_EA_INODE feature is enabled. - * - 0x8 - - __le32 - - e_value_size - - Length of attribute value. - * - 0xC - - __le32 - - e_hash - - Hash value of attribute name and attribute value. The kernel doesn't - update the hash for in-inode attributes, so for that case this value - must be zero, because e2fsck validates any non-zero hash regardless of - where the xattr lives. - * - 0x10 - - char - - e_name[e_name_len] - - Attribute name. Does not include trailing NULL. - -Attribute values can follow the end of the entry table. There appears to -be a requirement that they be aligned to 4-byte boundaries. The values -are stored starting at the end of the block and grow towards the -xattr_header/xattr_entry table. When the two collide, the overflow is -put into a separate disk block. If the disk block fills up, the -filesystem returns -ENOSPC. - -The first four fields of the ``ext4_xattr_entry`` are set to zero to -mark the end of the key list. - -Attribute Name Indices -~~~~~~~~~~~~~~~~~~~~~~ - -Logically speaking, extended attributes are a series of key=value pairs. -The keys are assumed to be NULL-terminated strings. To reduce the amount -of on-disk space that the keys consume, the beginning of the key string -is matched against the attribute name index. If a match is found, the -attribute name index field is set, and matching string is removed from -the key name. Here is a map of name index values to key prefixes: - -.. list-table:: - :widths: 16 64 - :header-rows: 1 - - * - Name Index - - Key Prefix - * - 0 - - (no prefix) - * - 1 - - “user.” - * - 2 - - “system.posix_acl_access” - * - 3 - - “system.posix_acl_default” - * - 4 - - “trusted.” - * - 6 - - “security.” - * - 7 - - “system.” (inline_data only?) - * - 8 - - “system.richacl” (SuSE kernels only?) - -For example, if the attribute key is “user.fubar”, the attribute name -index is set to 1 and the “fubar” name is recorded on disk. - -POSIX ACLs -~~~~~~~~~~ - -POSIX ACLs are stored in a reduced version of the Linux kernel (and -libacl's) internal ACL format. The key difference is that the version -number is different (1) and the ``e_id`` field is only stored for named -user and group ACLs.
Documentation/filesystems/ext4/directory.rst deleted +0 -453
453 lines not on this page · raw message
Documentation/filesystems/ext4/dynamic.rst +1411 -4
1,418 lines not on this page · raw message
Documentation/filesystems/ext4/ifork.rst deleted +0 -194
194 lines not on this page · raw message
Documentation/filesystems/ext4/inodes.rst deleted +0 -578
578 lines not on this page · raw message
Signature · 1 line
An old man doll... just what I always wanted! - Clara
kernel test robot
build botRe: [PATCH 3/4] Documentation: ext4: Slurp included subdocs in dynamic structures docs
kernel test robot noticed the following build warnings:
Hi Bagas,
kernel test robot noticed the following build warnings:
[auto build test WARNING on d3f825032091fc14c7d5e34bcd54317ae4246903]
url: https://github.com/intel-lab-lkp/linux/commits/Bagas-Sanjaya/Documentation-ext4-Slurp-included-subdocs-in-high-level-overview-docs/20250618-191724 base: d3f825032091fc14c7d5e34bcd54317ae4246903 patch link: https://lore.kernel.org/r/20250618111544.22602-4-bagasdotme%40gmail.com patch subject: [PATCH 3/4] Documentation: ext4: Slurp included subdocs in dynamic structures docs reproduce: (https://download.01.org/0day-ci/archive/20250619/[email protected]/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
All warnings (new ones prefixed by >>):
Warning: Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst references a file that doesn't exist: Documentation/dev-tools/gdb-kernel-debugging.rst
Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt
Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/leds/ti,tps6131x.yaml
Warning: arch/riscv/kernel/kexec_image.c references a file that doesn't exist: Documentation/riscv/boot-image-header.rst
Warning: drivers/clocksource/timer-armada-370-xp.c references a file that doesn't exist: Documentation/devicetree/bindings/timer/marvell,armada-370-xp-timer.txt
>> Warning: fs/ext4/inode-test.c references a file that doesn't exist: Documentation/filesystems/ext4/inodes.rst
Using alabaster theme
Signature · 2 lines
0-DAY CI Kernel Test Service https://github.com/intel/lkp-tests/wiki
PATCH 4/4 Documentation: ext4: Reduce toctree depth
In reply to Bagas Sanjayaext4 docs toctree has an arbitrary :maxdepth: of 6 (which is presumably intended to cover all possible heading levels), whereas the docs has at most 4-level section heading depth. Reduce the option instead to 2 (only showing the title and sections).
--- 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
Jonathan Corbet
maintainerQuoted 16 lines · Bagas Sanjaya
When a doc is included by other doc via include:: directive, Sphinx will pick the included doc and parse it independently from the including doc regardless if it is listed in the docs toctree. This, however, can exposes duplicate label warning that refers the label to itself (bug?) when the label is placed before any section heading, since Sphinx encounters the label twice, both when parsing the included and the including docs.
This could be solved by removing the problematic label. However, when it is heavily referenced by other doc (e.g. via :ref: directive), this can be a churn. Furthermore, the include:: usage pattern in kernel docs is to use it to included a common doc part that is shared by many docs (e.g. isonum.txt). ext4 docs, though, is the opposite: splitting docs into multiple reST files (subdocs) and including them in three master docs (
overview.rst,globals.rst, anddynamic.rst)
Quoted 6 lines
Let's slurp (squash) the subdocs instead. This will make the master docs larger of course (although not as big as KVM API docs), but one can use cross-reference labels without hitting aforementioned warning bug. Also, docs directory structure is tidier with only 4 files (master docs and
about.rst). As a bonus, also reduce toctree depth as to not spill the whole hierarchy.
"slurp" is not exactly a technical term that will make sense to readers of the changelogs.
But, more importantly... Might it be that the current file structure reflects the way the authors wanted to manage the docs? It seems to me that just organizing the existing files into a proper toctree would be rather less churny and yield useful results, no?
jon
Quoted 9 lines · Jonathan Corbet
Quoted 6 lines · Bagas Sanjaya
Let's slurp (squash) the subdocs instead. This will make the master docs larger of course (although not as big as KVM API docs), but one can use cross-reference labels without hitting aforementioned warning bug. Also, docs directory structure is tidier with only 4 files (master docs and
about.rst). As a bonus, also reduce toctree depth as to not spill the whole hierarchy.
Quoted 8 lines
"slurp" is not exactly a technical term that will make sense to readers of the changelogs.
But, more importantly... Might it be that the current file structure reflects the way the authors wanted to manage the docs? It seems to me that just organizing the existing files into a proper toctree would be rather less churny and yield useful results, no?
Agreed. The toctree approach was indeed my first thought ([1]).
Thanks.
[1]: https://lore.kernel.org/linux-doc/[email protected]/
Signature · 1 line
An old man doll... just what I always wanted! - Clara