[PATCH v2 1/2] Documentation: html: show sections in the sidebar

[Antonin Godard]

The current sidebar in the HTML version of the documentation does not
display the section titles because the toctree directives in the
top-level index.rst document do not contain ":caption:" properties.
Replacing the current section titles by ":caption:" properties would not
allow having text between those and the table of contents.

To workaround this issue, add the ":caption:" properties in the toctree
calls which makes them show up in the sidebar, but hide them from the
index page with a custom CSS addition.

Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Signed-off-by: Antonin Godard <antonin.godard@xxxxxxxxxxx>
---
 Documentation/index.rst                | 8 ++++++++
 Documentation/sphinx-static/custom.css | 6 ++++++
 2 files changed, 14 insertions(+)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index c0cf79a87c3a..a9eba8187de6 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -21,6 +21,7 @@ community and getting your work upstream.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Working with the development community
 
    Development process <process/development-process>
    Submitting patches <process/submitting-patches>
@@ -37,6 +38,7 @@ kernel.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Internal API manuals
 
    Core API <core-api/index>
    Driver APIs <driver-api/index>
@@ -50,6 +52,7 @@ Various other manuals with useful information for all kernel developers.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Development tools and processes
 
    Licensing rules <process/license-rules>
    Writing documentation <doc-guide/index>
@@ -71,6 +74,7 @@ developers seeking information on the kernel's user-space APIs.
 
 .. toctree::
    :maxdepth: 1
+   :caption: User-oriented documentation
 
    Administration <admin-guide/index>
    Build system <kbuild/index>
@@ -88,6 +92,7 @@ platform firmware.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Firmware-related documentation
 
    Firmware <firmware-guide/index>
    Firmware and Devicetree <devicetree/index>
@@ -98,6 +103,7 @@ Architecture-specific documentation
 
 .. toctree::
    :maxdepth: 2
+   :caption: Architecture-specific documentation
 
    CPU architectures <arch/index>
 
@@ -111,6 +117,7 @@ to reStructuredText format, or are simply too old.
 
 .. toctree::
    :maxdepth: 1
+   :caption: Other documentation
 
    Unsorted documentation <staging/index>
 
@@ -120,6 +127,7 @@ Translations
 
 .. toctree::
    :maxdepth: 2
+   :caption: Translations
 
    Translations <translations/index>
 
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 5aa0a1ed9864..0576d4fcb2a3 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -75,6 +75,12 @@ div.kerneltoc li.current ul { margin-left: 0; }
 div.kerneltoc { background-color: #eeeeee; }
 div.kerneltoc li.current ul { background-color: white; }
 
+/*
+ * Hide toctree captions on the welcome page, they should only be shown in the
+ * sidebar.
+ */
+section#the-linux-kernel-documentation p.caption { display: none; }
+
 /*
  * The CSS magic to toggle the contents on small screens.
  */

-- 
2.55.0