Skip to content

Slurp (squash) ext4 subdocs

Bagas Sanjaya linux-doc linux-ext4 lkml oe-kbuild-all 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest4 patches 2 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/4Documentation: ext4: Slurp included subdocs in high-level overview docsDocumentation/filesystems/ext4/allocators.rst Documentation/filesystems/ext4/atomic_writes.rst Documentation/filesystems/ext4/bigalloc.rst +8 more+809 -8310 replies
2/4Documentation: ext4: Slurp included subdocs in global structures docsDocumentation/filesystems/ext4/bitmaps.rst Documentation/filesystems/ext4/globals.rst Documentation/filesystems/ext4/group_descr.rst +4 more+1917 -19260 replies
3/4Documentation: ext4: Slurp included subdocs in dynamic structures docsDocumentation/filesystems/ext4/attributes.rst Documentation/filesystems/ext4/directory.rst Documentation/filesystems/ext4/dynamic.rst +2 more+1411 -14200 replies
4/4Documentation: ext4: Reduce toctree depthDocumentation/filesystems/ext4/index.rst+1 -10 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

Cover letter [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/[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