[PATCH 0/2] cgroup v2 docs update

[PATCH 0/2] cgroup v2 docs update

[Bagas Sanjaya]

Hi,

Just two independent docs update for cgroup v2. The shortlog below
should be self-explanatory.

Enjoy!

Bagas Sanjaya (2):
  Documentation: cgroup-v2: Use document path for cross-references
  Documentation: cgroup-v2: Replace manual table of contents with
    contents:: directive

 Documentation/accounting/psi.rst              |  2 -
 Documentation/admin-guide/cgroup-v1/index.rst |  2 -
 Documentation/admin-guide/cgroup-v2.rst       | 91 ++-----------------
 Documentation/scheduler/sched-ext.rst         |  2 -
 4 files changed, 7 insertions(+), 90 deletions(-)


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

[PATCH 1/2] Documentation: cgroup-v2: Use document path for cross-references

[Bagas Sanjaya]

Cross-references in cgroup v2 docs are written using :ref: directive
with full document path as anchor text. As there is a facility on
kernel docs that allows simply cross-references with target docs path,
replace the directive.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/accounting/psi.rst              |  2 --
 Documentation/admin-guide/cgroup-v1/index.rst |  2 --
 Documentation/admin-guide/cgroup-v2.rst       | 12 ++++++------
 Documentation/scheduler/sched-ext.rst         |  2 --
 4 files changed, 6 insertions(+), 12 deletions(-)

diff --git a/Documentation/accounting/psi.rst b/Documentation/accounting/psi.rst
index d455db3e580838..460e11f988fa89 100644
--- a/Documentation/accounting/psi.rst
+++ b/Documentation/accounting/psi.rst
@@ -1,5 +1,3 @@
-.. _psi:
-
 ================================
 PSI - Pressure Stall Information
 ================================
diff --git a/Documentation/admin-guide/cgroup-v1/index.rst b/Documentation/admin-guide/cgroup-v1/index.rst
index 99fbc8a64ba9e2..c0c6ac522569d4 100644
--- a/Documentation/admin-guide/cgroup-v1/index.rst
+++ b/Documentation/admin-guide/cgroup-v1/index.rst
@@ -1,5 +1,3 @@
-.. _cgroup-v1:
-
 ========================
 Control Groups version 1
 ========================
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index a1e3d431974c20..83bb69e3ab12a4 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -11,7 +11,7 @@ This is the authoritative documentation on the design, interface and
 conventions of cgroup v2.  It describes all userland-visible aspects
 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>`.
+v1 is available under Documentation/admin-guide/cgroup-v1/index.rst.
 
 .. CONTENTS
 
@@ -1081,7 +1081,7 @@ All cgroup core files are prefixed with "cgroup."
 	A read-write nested-keyed file.
 
 	Shows pressure stall information for IRQ/SOFTIRQ. See
-	:ref:`Documentation/accounting/psi.rst <psi>` for details.
+	Documentation/accounting/psi.rst for details.
 
 Controllers
 ===========
@@ -1132,7 +1132,7 @@ processes can be categorized as follows:
   without the ``cgroup_set_weight`` callback
 
 For details on when a process is under the fair-class scheduler or a BPF scheduler,
-check out :ref:`Documentation/scheduler/sched-ext.rst <sched-ext>`.
+check out Documentation/scheduler/sched-ext.rst.
 
 For each of the following interface files, the above categories
 will be referred to. All time durations are in microseconds.
@@ -1213,7 +1213,7 @@ will be referred to. All time durations are in microseconds.
 	A read-write nested-keyed file.
 
 	Shows pressure stall information for CPU. See
-	:ref:`Documentation/accounting/psi.rst <psi>` for details.
+	Documentation/accounting/psi.rst for details.
 
 	This file accounts for all the processes in the cgroup.
 
@@ -1903,7 +1903,7 @@ The following nested keys are defined.
 	A read-only nested-keyed file.
 
 	Shows pressure stall information for memory. See
-	:ref:`Documentation/accounting/psi.rst <psi>` for details.
+	Documentation/accounting/psi.rst for details.
 
 
 Usage Guidelines
@@ -2142,7 +2142,7 @@ IO Interface Files
 	A read-only nested-keyed file.
 
 	Shows pressure stall information for IO. See
-	:ref:`Documentation/accounting/psi.rst <psi>` for details.
+	Documentation/accounting/psi.rst for details.
 
 
 Writeback
diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index 404fe6126a7694..1e614958dd96c3 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -1,5 +1,3 @@
-.. _sched-ext:
-
 ==========================
 Extensible Scheduler Class
 ==========================
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/2] 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 files. While new sections are continously added,
manually-arranged table of contents (as reST comments) gets out-of-sync
with actual toctree as not all of these are added to it.

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

Signed-off-by: Bagas Sanjaya <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 83bb69e3ab12a4..2bf24aa6c08ebe 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 Documentation/admin-guide/cgroup-v1/index.rst.
 
-.. 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
 ============
-- 
An old man doll... just what I always wanted! - Clara

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

[Michal Koutný]

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

On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> manually-arranged table of contents (as reST comments) gets out-of-sync
> with actual toctree as not all of these are added to it.

Is this true? I generated HTML with this patch and the resulting ToC
matches what's in the comment.

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

Mauro, what's the best practice wrt consistent ToC and having it in
plaintext form?

Thanks,
Michal

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

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

[Bagas Sanjaya]

On 9/10/25 15:13, Michal Koutný wrote:
> On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>> manually-arranged table of contents (as reST comments) gets out-of-sync
>> with actual toctree as not all of these are added to it.
> 
> Is this true? I generated HTML with this patch and the resulting ToC
> matches what's in the comment.
> 

I see some sections are missing instead when compared to auto-generated
toctree.

Thanks.

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

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

[Jonathan Corbet]

Michal Koutný <mkoutny@suse.com> writes:

> On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>> manually-arranged table of contents (as reST comments) gets out-of-sync
>> with actual toctree as not all of these are added to it.
>
> Is this true? I generated HTML with this patch and the resulting ToC
> matches what's in the comment.
>
>> Replace it with automatically-generated table of contents via contents::
>> directive.
>
> Mauro, what's the best practice wrt consistent ToC and having it in
> plaintext form?

I fairly routinely get patches fixing manual TOCs that are not updated
to match changes elsewhere.  We have a nice system that can manage the
TOC automatically for us, it seems best to me to use it.

That said, if having the TOC in the plain-text version of the document
is deemed to be important, then it needs to be kept and manually
maintained.

Thanks,

jon

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

[Mauro Carvalho Chehab]

Em Wed, 10 Sep 2025 07:24:45 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Michal Koutný <mkoutny@suse.com> writes:
> 
> > On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@gmail.com> wrote:  
> >> manually-arranged table of contents (as reST comments) gets out-of-sync
> >> with actual toctree as not all of these are added to it.  
> >
> > Is this true? I generated HTML with this patch and the resulting ToC
> > matches what's in the comment.
> >  
> >> Replace it with automatically-generated table of contents via contents::
> >> directive.  
> >
> > Mauro, what's the best practice wrt consistent ToC and having it in
> > plaintext form?  
> 
> I fairly routinely get patches fixing manual TOCs that are not updated
> to match changes elsewhere.  We have a nice system that can manage the
> TOC automatically for us, it seems best to me to use it.

Agreed. If you use:


	.. toctree::
	   :maxdepth: 1
	   :glob:

	   * 

There won't be the need of manually updating the TOC tree.

That's said, I guess very few documents currently use grub:
	$ git grep :glob: Documentation/|wc -l
	7

Also, it has some drawbacks, as you can't control anymore the order 
where the docs will be placed. So, if this is important, you may need
to do something different, or maybe use things like (untested):

	.. toctree::
	   :maxdepth: 1
	   :glob:

	   pre*
	   main*
	   post*

> That said, if having the TOC in the plain-text version of the document
> is deemed to be important, then it needs to be kept and manually
> maintained.

Agreed.


Thanks,
Mauro

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

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Agreed. If you use:
>
>
> 	.. toctree::
> 	   :maxdepth: 1
> 	   :glob:
>
> 	   * 
>
> There won't be the need of manually updating the TOC tree.
>
> That's said, I guess very few documents currently use grub:
> 	$ git grep :glob: Documentation/|wc -l
> 	7
>
> Also, it has some drawbacks, as you can't control anymore the order 
> where the docs will be placed. So, if this is important, you may need
> to do something different, or maybe use things like (untested):

So this is a different level of TOC than what was originally being
discussed ... but now that we're here, I have to say that I am not a fan
of the use of wildcard toctrees in this way.  The index.rst files easily
become unstructured dumping grounds as it is; wildcards just make that
even worse.

IMO, every addition to a toctree should be considered with regard to
position, and the organization of the containing file in general.  But
then, I'm known to be an optimist.

jon

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

[Michal Koutný]

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

On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> cgroup v2 docs is a lengthy single docs as compared to cgroup v1 which
> is split into several files. While new sections are continously added,
> manually-arranged table of contents (as reST comments) gets out-of-sync
> with actual toctree as not all of these are added to it.
> 
> Replace it with automatically-generated table of contents via contents::
> directive.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/admin-guide/cgroup-v2.rst | 79 +------------------------
>  1 file changed, 1 insertion(+), 78 deletions(-)

The ship of plaintext ToC has sailed with .txt to .rst conversion. It's
better to maintain only the structure of headings and provide a
generated ToC.

Acked-by: Michal Koutný <mkoutny@suse.com>

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

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

[Tejun Heo]

Hello,

On Wed, Sep 10, 2025 at 07:24:45AM -0600, Jonathan Corbet wrote:
...
> I fairly routinely get patches fixing manual TOCs that are not updated
> to match changes elsewhere.  We have a nice system that can manage the
> TOC automatically for us, it seems best to me to use it.
> 
> That said, if having the TOC in the plain-text version of the document
> is deemed to be important, then it needs to be kept and manually
> maintained.

Wouldn't it be better to have some automated script which triggers on
mismatching TOC so that these get fixed up. I think people (including me) do
read the plain text version, so it'd be a shame if we lose TOC in the source
file.

Thanks.

-- 
tejun

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

[Bagas Sanjaya]

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

On Wed, Sep 10, 2025 at 06:44:22AM -1000, Tejun Heo wrote:
> Hello,
> 
> On Wed, Sep 10, 2025 at 07:24:45AM -0600, Jonathan Corbet wrote:
> ...
> > I fairly routinely get patches fixing manual TOCs that are not updated
> > to match changes elsewhere.  We have a nice system that can manage the
> > TOC automatically for us, it seems best to me to use it.
> > 
> > That said, if having the TOC in the plain-text version of the document
> > is deemed to be important, then it needs to be kept and manually
> > maintained.
> 
> Wouldn't it be better to have some automated script which triggers on
> mismatching TOC so that these get fixed up. I think people (including me) do
> read the plain text version, so it'd be a shame if we lose TOC in the source
> file.

In that case, I think we need to standardize these manual toctrees (perhaps
using custom directive?).

Thanks.

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

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

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

[Bagas Sanjaya]

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

On Wed, Sep 10, 2025 at 07:24:45AM -0600, Jonathan Corbet wrote:
> Michal Koutný <mkoutny@suse.com> writes:
> 
> > On Wed, Sep 10, 2025 at 02:23:34PM +0700, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> >> manually-arranged table of contents (as reST comments) gets out-of-sync
> >> with actual toctree as not all of these are added to it.
> >
> > Is this true? I generated HTML with this patch and the resulting ToC
> > matches what's in the comment.
> >
> >> Replace it with automatically-generated table of contents via contents::
> >> directive.
> >
> > Mauro, what's the best practice wrt consistent ToC and having it in
> > plaintext form?
> 
> I fairly routinely get patches fixing manual TOCs that are not updated
> to match changes elsewhere.  We have a nice system that can manage the
> TOC automatically for us, it seems best to me to use it.
> 
> That said, if having the TOC in the plain-text version of the document
> is deemed to be important, then it needs to be kept and manually
> maintained.

So for the v2, should I fix up the manual toctree to match autogenerated
one?

Thanks.

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

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