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@xxxxxxxxxx>
---
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
