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 <[email protected]>
---
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
Costa Shulyupin <[email protected]> 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
On 7/24/23 14:21, Jonathan Corbet wrote:
> Costa Shulyupin <[email protected]> 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
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.
--
~Randy
> 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?
Costa Shulyupin <[email protected]> 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
Mission: Make the documentation more readable, organized and maintainable.
NB: no information content is lost of changed on the rendered top page.
This patch demonstrates rework of the only the first section
of the top page for review. The proposal is to rework all sections.
Summary of changes:
- Heading "Working with the development community" is converted into
branch of toctree and visually moved after the text
"The essential guides for interacting ..."
- toctree list is split into separated file. Please don't worry, the
content of the list is incorporated to the top page because of
`:maxdepth: 2`
- vertical bar '|' add empty line for better visual distribution
Technical explanations:
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.
Benefit:
- toc on side bar is expandable and collapsible
---
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 <[email protected]>
---
Documentation/index.rst | 12 +++---------
Documentation/process/main.rst | 13 +++++++++++++
2 files changed, 16 insertions(+), 9 deletions(-)
create mode 100644 Documentation/process/main.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9dfdc826618c..560eb0bc78dd 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -13,21 +13,15 @@ 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.
.. 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
====================
diff --git a/Documentation/process/main.rst b/Documentation/process/main.rst
new file mode 100644
index 000000000000..40bab4ff8198
--- /dev/null
+++ b/Documentation/process/main.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+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>
--
2.41.0
Costa Shulyupin <[email protected]> writes:
> Mission: Make the documentation more readable, organized and maintainable.
>
> NB: no information content is lost of changed on the rendered top page.
>
> This patch demonstrates rework of the only the first section
> of the top page for review. The proposal is to rework all sections.
>
> Summary of changes:
> - Heading "Working with the development community" is converted into
> branch of toctree and visually moved after the text
> "The essential guides for interacting ..."
> - toctree list is split into separated file. Please don't worry, the
> content of the list is incorporated to the top page because of
> `:maxdepth: 2`
> - vertical bar '|' add empty line for better visual distribution
I will repeat. I do not support carving useful stuff out of the front
page in this way. The front page does not exist just to make a
nice-looking sidebar.
> Technical explanations:
> 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.
*This* is where the problem lies. I have started looking at it again,
but digging deep into the Sphinx code can be painful at times.
jon