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

Bagas Sanjaya <bagasdotme@gmail.com> writes:

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

"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

On Thu, Jun 19, 2025 at 01:56:48PM -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > 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?
> 

Agreed. The toctree approach was indeed my first thought ([1]).

Thanks.

[1]: https://lore.kernel.org/linux-doc/aEpAD2jcemzvoJlQ@archie.me/

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