linux-kernel - [PATCH v3 0/7] 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: <20220927160559.97154-1-corbet@lwn.net>
Date:   Tue, 27 Sep 2022 10:05:52 -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>,
        Joe Perches <joe@...ches.com>,
        David Vernet <void@...ifault.com>,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH v3 0/7] 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/

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.

Jonathan Corbet (7):
  docs: promote the title of process/index.rst
  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: put atomic*.txt and memory-barriers.txt into the core-api book
  docs: add a man-pages link to the front page

 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                       | 156 ++++++------------
 Documentation/process/index.rst               |   1 +
 Documentation/staging/index.rst               |  42 -----
 Documentation/subsystem-apis.rst              |  58 +++++++
 scripts/checkpatch.pl                         |   2 +-
 11 files changed, 175 insertions(+), 153 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