diff mbox series

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

Message ID 20230724193118.2204673-1-costa.shul@redhat.com
State New
Headers
Series [RFC] rework top page and organize toc on the sidebar |

Commit Message

Costa Shulyupin July 24, 2023, 7:31 p.m. UTC 
  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

Comments

Jonathan Corbet July 24, 2023, 9:21 p.m. UTC | #1 
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
Randy Dunlap July 25, 2023, 3:04 a.m. UTC | #2 
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.
Costa Shulyupin July 26, 2023, 5:55 a.m. UTC | #3 
> This patch is somewhat difficult to apply, as a result of:
> > Content-Type: text/plain; charset=true

This is caused by em dash in the context line:
The following manuals are written for *users* of the kernel — those who are

I haven't found how to fix it. Are there any tips?
Randy Dunlap July 26, 2023, 6:03 a.m. UTC | #4 
On 7/25/23 22:55, Costa Shulyupin wrote:
>> This patch is somewhat difficult to apply, as a result of:
>>> Content-Type: text/plain; charset=true
> 
> This is caused by em dash in the context line:
> The following manuals are written for *users* of the kernel — those who are
> 
> I haven't found how to fix it. Are there any tips?

Fix the email header or fix the em dash?

Did you use 'git send-email' for the patch? It seems to handle
UTF/UCS charsets AFAIK.

OTOH, any decent text editor can change the em dash to one or
two hyphens. (which I prefer)

cheers.
Jonathan Corbet July 26, 2023, 1:54 p.m. UTC | #5 
Costa Shulyupin <costa.shul@redhat.com> writes:

>> This patch is somewhat difficult to apply, as a result of:
>> > Content-Type: text/plain; charset=true
>
> This is caused by em dash in the context line:
> The following manuals are written for *users* of the kernel — those who are
>
> I haven't found how to fix it. Are there any tips?

No, it won't be the em-dash.  "true" is not a valid charset.

jon
diff mbox series

Patch

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.
+