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! - ClaraOn 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>
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
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
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
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
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
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
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
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
© 2016 - 2025 Red Hat, Inc.