[PATCH v3] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

[PATCH v3] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

[Bagas Sanjaya]

cgroup v2 docs is a lengthy single docs, as compared to cgroup v1 which
is split into several reST files. Meanwhile, its manually-arranged table
of contents can get (and indeed) out-of-sync with actual contents when
new sections forget to be added to it.

Replace it with automatically-generated table of contents via contents::
directive.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Changes since v2 [1]:

  * Revert back to v1 approach [2] (Michal)

[1]: https://lore.kernel.org/lkml/20250915081942.25077-1-bagasdotme@gmail.com/
[2]: https://lore.kernel.org/lkml/20250910072334.30688-3-bagasdotme@gmail.com/

 Documentation/admin-guide/cgroup-v2.rst | 79 +------------------------
 1 file changed, 1 insertion(+), 78 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index a1e3d431974c20..fdd3ee6cfe87a4 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -13,84 +13,7 @@ of cgroup including core and specific controller behaviors.  All
 future changes must be reflected in this document.  Documentation for
 v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgroup-v1>`.
 
-.. CONTENTS
-
-   1. Introduction
-     1-1. Terminology
-     1-2. What is cgroup?
-   2. Basic Operations
-     2-1. Mounting
-     2-2. Organizing Processes and Threads
-       2-2-1. Processes
-       2-2-2. Threads
-     2-3. [Un]populated Notification
-     2-4. Controlling Controllers
-       2-4-1. Enabling and Disabling
-       2-4-2. Top-down Constraint
-       2-4-3. No Internal Process Constraint
-     2-5. Delegation
-       2-5-1. Model of Delegation
-       2-5-2. Delegation Containment
-     2-6. Guidelines
-       2-6-1. Organize Once and Control
-       2-6-2. Avoid Name Collisions
-   3. Resource Distribution Models
-     3-1. Weights
-     3-2. Limits
-     3-3. Protections
-     3-4. Allocations
-   4. Interface Files
-     4-1. Format
-     4-2. Conventions
-     4-3. Core Interface Files
-   5. Controllers
-     5-1. CPU
-       5-1-1. CPU Interface Files
-     5-2. Memory
-       5-2-1. Memory Interface Files
-       5-2-2. Usage Guidelines
-       5-2-3. Memory Ownership
-     5-3. IO
-       5-3-1. IO Interface Files
-       5-3-2. Writeback
-       5-3-3. IO Latency
-         5-3-3-1. How IO Latency Throttling Works
-         5-3-3-2. IO Latency Interface Files
-       5-3-4. IO Priority
-     5-4. PID
-       5-4-1. PID Interface Files
-     5-5. Cpuset
-       5.5-1. Cpuset Interface Files
-     5-6. Device
-     5-7. RDMA
-       5-7-1. RDMA Interface Files
-     5-8. DMEM
-     5-9. HugeTLB
-       5.9-1. HugeTLB Interface Files
-     5-10. Misc
-       5.10-1 Miscellaneous cgroup Interface Files
-       5.10-2 Migration and Ownership
-     5-11. Others
-       5-11-1. perf_event
-     5-N. Non-normative information
-       5-N-1. CPU controller root cgroup process behaviour
-       5-N-2. IO controller root cgroup process behaviour
-   6. Namespace
-     6-1. Basics
-     6-2. The Root and Views
-     6-3. Migration and setns(2)
-     6-4. Interaction with Other Namespaces
-   P. Information on Kernel Programming
-     P-1. Filesystem Support for Writeback
-   D. Deprecated v1 Core Features
-   R. Issues with v1 and Rationales for v2
-     R-1. Multiple Hierarchies
-     R-2. Thread Granularity
-     R-3. Competition Between Inner Nodes and Threads
-     R-4. Other Interface Issues
-     R-5. Controller Issues and Remedies
-       R-5-1. Memory
-
+.. contents::
 
 Introduction
 ============

base-commit: 1f783f733450f72725c0040a2b3075614fa0fb5c
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v3] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

[Tejun Heo]

Hello,

On Thu, Sep 18, 2025 at 02:40:49PM +0700, Bagas Sanjaya wrote:
> cgroup v2 docs is a lengthy single docs, as compared to cgroup v1 which
> is split into several reST files. Meanwhile, its manually-arranged table
> of contents can get (and indeed) out-of-sync with actual contents when
> new sections forget to be added to it.
> 
> Replace it with automatically-generated table of contents via contents::
> directive.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

I don't think I'm going to apply this. Sure, it can get out of sync but I'd
rather have TOC which sometimes is a bit out of sync than none at all.

Thanks.

-- 
tejun

Re: [PATCH v3] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 685 bytes --]

On Thu, Sep 18, 2025 at 05:44:56AM -1000, Tejun Heo <tj@kernel.org> wrote:
> I don't think I'm going to apply this. Sure, it can get out of sync but I'd
> rather have TOC which sometimes is a bit out of sync than none at all.

The TOC is in the generated output :-p

I understand you want this "[PATCH v2 4/4] Documentation: cgroup-v2: Sync
manual toctree" [1], which is also fine.
But I'd drop this "[PATCH v2 2/4] Documentation: cgroup-v2: Add section
numbers" [2], because that adds more places for out-of-syncness.

Michal

[1] https://lore.kernel.org/lkml/20250915081942.25077-5-bagasdotme@gmail.com/
[2] https://lore.kernel.org/lkml/20250915081942.25077-3-bagasdotme@gmail.com/


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

Re: [PATCH v3] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

[Tejun Heo]

Hello,

On Thu, Sep 18, 2025 at 05:55:07PM +0200, Michal Koutný wrote:
> On Thu, Sep 18, 2025 at 05:44:56AM -1000, Tejun Heo <tj@kernel.org> wrote:
> > I don't think I'm going to apply this. Sure, it can get out of sync but I'd
> > rather have TOC which sometimes is a bit out of sync than none at all.
> 
> The TOC is in the generated output :-p

I know it's tongue-in-cheek but one big benefit of the doc format we use is
that these are still very readable as a plain text document. In general, I
don't want to make changes that worsens plain text accessibility.

> I understand you want this "[PATCH v2 4/4] Documentation: cgroup-v2: Sync
> manual toctree" [1], which is also fine.
> But I'd drop this "[PATCH v2 2/4] Documentation: cgroup-v2: Add section
> numbers" [2], because that adds more places for out-of-syncness.
> 
> [1] https://lore.kernel.org/lkml/20250915081942.25077-5-bagasdotme@gmail.com/
> [2] https://lore.kernel.org/lkml/20250915081942.25077-3-bagasdotme@gmail.com/

Sure, that makes sense. Will apply [1].

Thanks

---
tejun

Thank.s

-- 
tejun

Re: [PATCH v3] Documentation: cgroup-v2: Replace manual table of contents with contents:: directive

[Bagas Sanjaya]

On 9/18/25 22:59, Tejun Heo wrote:
> Hello,
> 
> On Thu, Sep 18, 2025 at 05:55:07PM +0200, Michal Koutný wrote:
>> On Thu, Sep 18, 2025 at 05:44:56AM -1000, Tejun Heo <tj@kernel.org> wrote:
>>> I don't think I'm going to apply this. Sure, it can get out of sync but I'd
>>> rather have TOC which sometimes is a bit out of sync than none at all.
>>
>> The TOC is in the generated output :-p
> 
> I know it's tongue-in-cheek but one big benefit of the doc format we use is
> that these are still very readable as a plain text document. In general, I
> don't want to make changes that worsens plain text accessibility.
> 

OK, thanks!

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