| 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
| ||
|
Message-ID: <20230724193118.2204673-1-costa.shul@redhat.com>
Date: Mon, 24 Jul 2023 22:31:16 +0300
From: Costa Shulyupin <costa.shul@...hat.com>
To: Jonathan Corbet <corbet@....net>, Miguel Ojeda <ojeda@...nel.org>,
Alex Gaynor <alex.gaynor@...il.com>,
Wedson Almeida Filho <wedsonaf@...il.com>,
Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>,
Björn Roy Baron <bjorn3_gh@...tonmail.com>,
Benno Lossin <benno.lossin@...ton.me>,
linux-doc@...r.kernel.org (open list:DOCUMENTATION),
linux-kernel@...r.kernel.org (open list),
workflows@...r.kernel.org (open list:DOCUMENTATION PROCESS),
rust-for-linux@...r.kernel.org (open list:RUST)
Cc: Costa Shulyupin <costa.shul@...hat.com>
Subject: [RFC PATCH] rework top page and organize toc on the sidebar
Template {{ toctree(maxdepth=3) }} in
Documentation/sphinx/templates/kernel-toc.html
uses directives toctree and doesn't use sections on the top page
Documentation/index.rst
to generate expandable toc on the sidebar.
BTW, other template {{ toc }} uses only sections, and doesn't
use directives toctree.
Summary of changes:
- split top page index.rst to several pages
- convert sections of Documentation/index.rst to hierarchical toctree
- vertical bars '|' add empty lines
Benefits:
- collapsed toc is just seven short lines length
- toc is expandable
References:
- https://www.sphinx-doc.org/en/master/development/templating.html#toctree
- https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
- https://www.sphinx-doc.org/en/master/development/templating.html#toc
- https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
- https://sphinx-rtd-theme.readthedocs.io/
Signed-off-by: Costa Shulyupin <costa.shul@...hat.com>
---
Documentation/development.rst | 19 +++++++++
Documentation/index.rst | 78 +++++++++-------------------------
Documentation/internal-api.rst | 12 ++++++
Documentation/low-level.rst | 24 +++++++++++
Documentation/process/main.rst | 16 +++++++
Documentation/user.rst | 21 +++++++++
6 files changed, 112 insertions(+), 58 deletions(-)
create mode 100644 Documentation/development.rst
create mode 100644 Documentation/internal-api.rst
create mode 100644 Documentation/low-level.rst
create mode 100644 Documentation/process/main.rst
create mode 100644 Documentation/user.rst
diff --git a/Documentation/development.rst b/Documentation/development.rst
new file mode 100644
index 000000000000..8d8eea6d4491
--- /dev/null
+++ b/Documentation/development.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Development processes
+=====================
+
+Various other manuals with useful information for all kernel developers.
+
+.. toctree::
+ :maxdepth: 1
+
+ process/license-rules
+ doc-guide/index
+ dev-tools/index
+ dev-tools/testing-overview
+ kernel-hacking/index
+ trace/index
+ fault-injection/index
+ livepatch/index
+ rust/index
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9dfdc826618c..3c0efebba9e9 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -13,94 +13,56 @@ documents into a coherent whole. Please note that improvements to the
documentation are welcome; join the linux-doc list at vger.kernel.org if
you want to help out.
-Working with the development community
-======================================
+|
The essential guides for interacting with the kernel's development
-community and getting your work upstream.
+community and getting your work upstream:
.. toctree::
- :maxdepth: 1
-
- process/development-process
- process/submitting-patches
- Code of conduct <process/code-of-conduct>
- maintainer/index
- All development-process docs <process/index>
+ :maxdepth: 2
+ process/main
-Internal API manuals
-====================
+|
Manuals for use by developers working to interface with the rest of the
-kernel.
+kernel:
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
- core-api/index
- driver-api/index
- subsystem-apis
- Locking in the kernel <locking/index>
+ internal-api
-Development tools and processes
-===============================
+|
-Various other manuals with useful information for all kernel developers.
+Various other manuals with useful information for all kernel developers:
.. toctree::
- :maxdepth: 1
-
- process/license-rules
- doc-guide/index
- dev-tools/index
- dev-tools/testing-overview
- kernel-hacking/index
- trace/index
- fault-injection/index
- livepatch/index
- rust/index
+ :maxdepth: 2
+ development
-User-oriented documentation
-===========================
+|
The following manuals are written for *users* of the kernel — those who are
trying to get it to work optimally on a given system and application
-developers seeking information on the kernel's user-space APIs.
+developers seeking information on the kernel's user-space APIs:
.. toctree::
- :maxdepth: 1
-
- admin-guide/index
- The kernel build system <kbuild/index>
- admin-guide/reporting-issues.rst
- User-space tools <tools/index>
- userspace-api/index
-
-See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
-which are kept separately from the kernel's own documentation.
-
-Firmware-related documentation
-==============================
-The following holds information on the kernel's expectations regarding the
-platform firmwares.
-
-.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
- firmware-guide/index
- devicetree/index
+ user
+|
-Architecture-specific documentation
-===================================
+Low level heardware depended documentation:
.. toctree::
:maxdepth: 2
- arch/index
+ low-level
+|
Other documentation
===================
diff --git a/Documentation/internal-api.rst b/Documentation/internal-api.rst
new file mode 100644
index 000000000000..c4aa757cbca7
--- /dev/null
+++ b/Documentation/internal-api.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Internal API manuals
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ core-api/index
+ driver-api/index
+ subsystem-apis
+ Locking in the kernel <locking/index>
diff --git a/Documentation/low-level.rst b/Documentation/low-level.rst
new file mode 100644
index 000000000000..4288633b37af
--- /dev/null
+++ b/Documentation/low-level.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Low level
+=========
+
+Firmware-related documentation
+------------------------------
+The following holds information on the kernel's expectations regarding the
+platform firmwares.
+
+.. toctree::
+ :maxdepth: 1
+
+ firmware-guide/index
+ devicetree/index
+
+
+Architecture-specific documentation
+-----------------------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ arch/index
diff --git a/Documentation/process/main.rst b/Documentation/process/main.rst
new file mode 100644
index 000000000000..732dab311d6d
--- /dev/null
+++ b/Documentation/process/main.rst
@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Community
+=========
+
+Working with the development community
+
+
+.. toctree::
+ :maxdepth: 1
+
+ development-process
+ submitting-patches
+ Code of conduct <code-of-conduct>
+ ../maintainer/index
+ All development-process docs <../process/index>
diff --git a/Documentation/user.rst b/Documentation/user.rst
new file mode 100644
index 000000000000..22151edc5bcc
--- /dev/null
+++ b/Documentation/user.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+User-oriented documentation
+===========================
+
+The following manuals are written for *users* of the kernel — those who are
+trying to get it to work optimally on a given system and application
+developers seeking information on the kernel's user-space APIs.
+
+.. toctree::
+ :maxdepth: 1
+
+ admin-guide/index
+ The kernel build system <kbuild/index>
+ admin-guide/reporting-issues.rst
+ User-space tools <tools/index>
+ userspace-api/index
+
+See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
+which are kept separately from the kernel's own documentation.
+
--
2.41.0
Powered by blists - more mailing lists