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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20220922204138.153146-1-corbet@lwn.net>
Date:   Thu, 22 Sep 2022 14:41:31 -0600
From:   Jonathan Corbet <corbet@....net>
To:     linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org,
        Thorsten Leemhuis <linux@...mhuis.info>,
        Kees Cook <keescook@...omium.org>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH v2 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 "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