[PATCH 0/4] Rewrite the top-level index.rst

* [PATCH 0/4] Rewrite the top-level index.rst
@ 2022-09-01 23:16 Jonathan Corbet
  2022-09-01 23:16 ` [PATCH 1/4] docs: promote the title of process/index.html Jonathan Corbet
                   ` (4 more replies)
  0 siblings, 5 replies; 10+ messages in thread
From: Jonathan Corbet @ 2022-09-01 23:16 UTC (permalink / raw)
  To: linux-doc; +Cc: linux-kernel, Jonathan Corbet

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 "Alabaster" 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.

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.

Jonathan Corbet (4):
  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

 Documentation/conf.py            |   3 +-
 Documentation/index.rst          | 157 +++++++++++--------------------
 Documentation/process/index.rst  |   1 +
 Documentation/subsystem-apis.rst |  56 +++++++++++
 4 files changed, 116 insertions(+), 101 deletions(-)
 create mode 100644 Documentation/subsystem-apis.rst

-- 
2.37.2

^ permalink raw reply	[flat|nested] 10+ messages in thread