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/ Those pages are rendered with the "Book" theme, which pays attention to the html_sidebar directive. I am not proposing a switch to that theme (I just picked it at random), but I do think we should reconsider the default theme at some point - or just create our own theme. 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 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. Unless I get screams I plan to slip this into 6.1. It is definitely not the final form of the front page, but I doubt we'll ever get there; we can change it in whatever ways make sense. Jonathan Corbet (7): docs: promote the title of process/index.html docs: Rewrite the front page docs: reconfigure the HTML left column docs: remove some index.rst cruft docs: move asm-annotations.rst into core-api docs: Expand the front-page CPU-architecture section docs: put atomic*.txt and memory-barriers.txt into the core-api book Documentation/conf.py | 3 +- .../{ => core-api}/asm-annotations.rst | 7 +- Documentation/core-api/index.rst | 4 + .../core-api/wrappers/atomic_bitops.rst | 18 ++ Documentation/core-api/wrappers/atomic_t.rst | 19 +++ .../core-api/wrappers/memory-barriers.rst | 18 ++ Documentation/index.rst | 154 ++++++------------ Documentation/process/index.rst | 1 + Documentation/staging/index.rst | 42 ----- Documentation/subsystem-apis.rst | 58 +++++++ 10 files changed, 172 insertions(+), 152 deletions(-) rename Documentation/{ => core-api}/asm-annotations.rst (97%) create mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst create mode 100644 Documentation/core-api/wrappers/atomic_t.rst create mode 100644 Documentation/core-api/wrappers/memory-barriers.rst create mode 100644 Documentation/subsystem-apis.rst -- 2.37.2
