Re: [PATCH 0/4] Slurp (squash) ext4 subdocs

[Jonathan Corbet <corbet@lwn.net>]

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