Hi,
On Tue, 14 Feb 2023 11:33:09 -0700, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> writes:
>
>> Is there a reason that the main index's "sections" (single underline)
>> don't show up in the sidebar index? Is that on purpose?
>> Or just a relic of them being "sections"?
>
> That's just how the sidebar gets generated. I would much rather see the
> sections there...but if we want that, I think we'll have to implement it
> ourselves.
I'd say that the reason why you don't see sections of the main index in
the sidebar is because the main index.rst *isn't* listed in any of
"toctree" directives.
So, if you want those "sections" in the sidebar, you need to create
a .rst file and list it in a toctree of main index.
The RTD theme has exactly the same behavior ever since commit
0c7b4366f1ab ("docs: Rewrite the front page").
Furthermore, as there are quite a few pages which belong to multiple
toctrees, sidebar sometimes behaves weirdly.
For example, see the sidebar at:
https://www.kernel.org/doc/html/next/process/submitting-patches.html
(built on current linux-next)
You will see that the "Submitting patches ..." title is expanded
twice in the sidebar.
Don't you think this looks weird? ;-)
I think the patch appended below (on top of current docs-next)
would have been a better approach, where each .rst file is listed
only once in the whole toctree. The refurbished part of main index
is moved to index-frequent.rst and toctrees are replaced with
lists of :doc: references.
Per-directory indexes are listed in the main index's toctree
below the index-frequent.
I'm not saying this is "the" right approach.
There can be many ways to accomplish the same result, I suppose.
I'll submit this change as a proper patch if I can get positive
feedback.
Hope this helps.
Thanks, Akira
------------------
diff --git a/Documentation/index-frequent.rst b/Documentation/index-frequent.rst
new file mode 100644
index 000000000000..5d412be69196
--- /dev/null
+++ b/Documentation/index-frequent.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================
+Frequently Referenced Documents
+===============================
+
+This is a list of links to kernel documents which would help
+(prospective) kernel developers most.
+
+Working with the development community
+======================================
+
+The essential guides for interacting with the kernel's development
+community and getting your work upstream.
+
+ * process/development-process.rst
+ * process/submitting-patches.rst
+ * :doc:`Code of condust <process/code-of-conduct>`
+ * maintainer/index.rst
+ * :doc:`All development-process docs <process/index>`
+
+
+Internal API manuals
+====================
+
+Manuals for use by developers working to interface with the rest of the
+kernel.
+
+ * core-api/index.rst
+ * driver-api/index.rst
+ * subsystems-apis/index.rst
+ * :doc:`Locking in the kernel <locking/index>`
+
+
+Development tools and processes
+===============================
+
+Various other manuals with useful information for all kernel developers.
+
+ * process/license-rules.rst
+ * doc-guide/index.rst
+ * dev-tools/index.rst
+ * dev-tools/testing-overview.rst
+ * kernel-hacking/index.rst
+ * trace/index.rst
+ * fault-injection/index.rst
+ * livepatch/index.rst
+ * rust/index.rst
+
+
+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.
+
+ * admin-guide/index.rst
+ * :doc:`The kernel build system <kbuild/index>`
+ * admin-guide/reporting-issues.rst
+ * :doc:`User-space tools <tools/index>`
+ * userspace-api/index.rst
+
+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.
+
+ * firmware-guide/index.rst
+ * devicetree/index.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index bf6aa681c960..a50681452fab 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -12,86 +12,41 @@ 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
+ index-frequent
-Internal API manuals
---------------------
-Manuals for use by developers working to interface with the rest of the
-kernel.
+Per-subdirectory documents (referenced from above)
+--------------------------------------------------
.. toctree::
:maxdepth: 1
+ process/index
+ maintainer/index
core-api/index
driver-api/index
subsystem-apis
- Locking in the kernel <locking/index>
-
-Development tools and processes
--------------------------------
-
-Various other manuals with useful information for all kernel developers.
-
-.. toctree::
- :maxdepth: 1
+ locking/index
- 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
-
-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>
+ kbuild/index
+ 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
-
firmware-guide/index
devicetree/index
-
Architecture-specific documentation
-----------------------------------
@@ -123,6 +78,6 @@ Translations
translations/index
Indices and tables
-==================
+------------------
* :ref:`genindex`
--
