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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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