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@xxxxxxxxxx>
---
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
