diff mbox series

[RFC,v2] docs: rework "Working with the development community"

Message ID 20230726184939.3118350-1-costa.shul@redhat.com
State New
Headers
Series [RFC,v2] docs: rework "Working with the development community" |

Commit Message

Costa Shulyupin July 26, 2023, 6:49 p.m. UTC 
  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@redhat.com>
---
 Documentation/index.rst        | 12 +++---------
 Documentation/process/main.rst | 13 +++++++++++++
 2 files changed, 16 insertions(+), 9 deletions(-)
 create mode 100644 Documentation/process/main.rst

Comments

Jonathan Corbet July 26, 2023, 7:30 p.m. UTC | #1 
Costa Shulyupin <costa.shul@redhat.com> 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
diff mbox series

Patch

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>