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/20250610091200.54075-2-bagasdotme@xxxxxxxxx/ 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 -- An old man doll... just what I always wanted! - Clara
