On 9/27/22 09:05, Jonathan Corbet wrote: > The top-level index.rst file is the entry point for the kernel's > documentation, especially for readers of the HTML output. It is currently > a mess containing everything we thought to throw in there. Firefox says it > would require 26 pages of paper to print it. That is not a user-friendly > introduction. > > This series aims to improve our documentation entry point with a focus on > rewriting index.rst. The result is, IMO, simpler and more approachable. > For anybody who wants to see the rendered results without building the > docs, have a look at: > > https://static.lwn.net/kerneldoc/ LGTM. Thanks. for the series: Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> > This time around I've rendered the pages using the "Read The Docs" theme, > since that's what everybody will get by default. That theme ignores the > directives regarding the left column, so the results are not as good there. > I have a series proposing a default-theme change in the works, but that's a > separate topic. > > This is only a beginning; I think this kind of organizational effort has to > be pushed down into the lower layers of the docs tree itself. But one has > to start somewhere. > > CHANGES from v2: now with less sloppiness. I've tried to respond to all of > the review comments. scripts/checkpatch.pl has been updated to match the > new location of asm-annotations.rst. There is also now a link to the man > pages in the user-oriented documentation section. > > CHANGES from v1: I've tried to address the comments from v1, further > cleaning up the front page. I've added the "reporting issues" and "kernel > testing" documents there, and done a bit of cleanup. There is plenty more > yet to be done. -- ~Randy
