On 2/16/24 23:31, Vegard Nossum wrote: > On 16/02/2024 15:58, Jonathan Corbet wrote: >> Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> writes: >> >>> On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote: >>>> rst basically allows any order of the heading underlines, and their >>>> relative hierarchy is determined by how they show up in each document, >>>> it's not specified by rst. However, it would be much easier for everyone >>>> if all the kernel documents followed the same style. >>> >>> Agreed, someone should pick a style and sweep the whole directory and >>> sync them up to the agreed formatting. :) >> >> Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :) > > I have a (very long and ugly) script that can fix these up to a > consistent style, the attached patch is the result of running it on > Documentation/process/ only. > > I've done builds before and after the patch and diffed the resulting > HTML files, they show no difference. (HOWEVER, you do need a 'make > cleandocs' in between, as it seems doing 'make htmldocs; find > Documentation | xargs touch; make htmldocs' is going to change the > generated HTML for the sidebar -- another issue to look into at some > point, I guess; maybe it's specific to the Sphinx version I used here, > 4.3.2.) > > The script will leave alone any file that it doesn't quite understand > (e.g. for a lot of the translations there are way more underlines than > characters in the heading and it doesn't match up with the byte count > either). > > Anyway, the question is: Is this worth doing in the first place, or is > it just churn? I assume just after -rc1 would be the ideal time to > submit these to avoid conflicts. Yes, do it, please. Thanks. -- #Randy
