[RFC PATCH] rework top page and organize toc on the sidebar

[RFC PATCH] rework top page and organize toc on the sidebar

[Costa Shulyupin]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=true, Size: 7402 bytes --]

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@redhat.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

Re: [RFC PATCH] rework top page and organize toc on the sidebar

[Jonathan Corbet]

Costa Shulyupin <costa.shul@redhat.com> writes:

> 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/

What is the purpose of all these links in a patch changelog?

This patch is somewhat difficult to apply, as a result of:

> Content-Type: text/plain; charset=true

But the real problem is that you seem to have ignored my last message.
The purpose of the front page isn't to create a nice-looking sidebar, it
is the entry point to our documentation as a whole.  I am all for a
better sidebar, but this is not the way to do it.

jon

Re: [RFC PATCH] rework top page and organize toc on the sidebar

[Randy Dunlap]

On 7/24/23 14:21, Jonathan Corbet wrote:
> Costa Shulyupin <costa.shul@redhat.com> writes:
> 
>> 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/
> 
> What is the purpose of all these links in a patch changelog?
> 
> This patch is somewhat difficult to apply, as a result of:
> 
>> Content-Type: text/plain; charset=true

I didn't have any problem applying and testing it.

> But the real problem is that you seem to have ignored my last message.
> The purpose of the front page isn't to create a nice-looking sidebar, it
> is the entry point to our documentation as a whole.  I am all for a
> better sidebar, but this is not the way to do it.

Regardless of what the purpose of the front page is, I prefer this one
from Costa.  The other one is a huge mess.

-- 
~Randy