linux-kernel - [RFC PATCH v2] docs: rework "Working with the development community"

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

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20230726184939.3118350-1-costa.shul@redhat.com>
Date:   Wed, 26 Jul 2023 21:49:37 +0300
From:   Costa Shulyupin <costa.shul@...hat.com>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, workflows@...r.kernel.org
Cc:     Costa Shulyupin <costa.shul@...hat.com>
Subject: [RFC PATCH v2] docs: rework "Working with the development community"

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 <costa.shul@...hat.com>
---
 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