Message-ID: <20250618111544.22602-1-bagasdotme@gmail.com>
Date: Wed, 18 Jun 2025 18:15:33 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	Linux Documentation <linux-doc@...r.kernel.org>,
	Linux ext4 <linux-ext4@...r.kernel.org>
Cc: "Theodore Ts'o" <tytso@....edu>,
	Andreas Dilger <adilger.kernel@...ger.ca>,
	Jonathan Corbet <corbet@....net>,
	"Darrick J. Wong" <djwong@...nel.org>,
	"Ritesh Harjani (IBM)" <ritesh.list@...il.com>,
	Bagas Sanjaya <bagasdotme@...il.com>
Subject: [PATCH 0/4] 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/20250610091200.54075-2-bagasdotme@gmail.com/

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

Powered by blists - more mailing lists