[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Message-Id: <20220901231632.518583-1-corbet@lwn.net>
Date: Thu, 1 Sep 2022 17:16:28 -0600
From: Jonathan Corbet <corbet@....net>
To: linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>
Subject: [PATCH 0/4] Rewrite the top-level index.rst
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
Powered by blists - more mailing lists