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.

Additionally, make the section titles in the sidebar bold to make them
stand-out.

This makes the overall structure of the documentation clearer from the
sidebar directly.

PS: This is how I've implemented this in the Yocto Project
documentation[1] where I faced the same issue. See also the index.rst
file[2] (which was by the way inspired by the kernel's own index.rst)
and CSS addition[3].

[1]: https://docs.yoctoproject.org/dev/
[2]: https://git.yoctoproject.org/yocto-docs/tree/documentation/index.rst
[3]: https://git.yoctoproject.org/yocto-docs/tree/documentation/sphinx-static/theme_overrides.css#n106

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- Apply RB and TB from Randy on patch 1/2.
- Remove whitespace before section title and first subsection.
- Link to v1: https://patch.msgid.link/20260803-show-sections-in-sidebar-v1-0-b4fdc847525d@bootlin.com

---
Antonin Godard (2):
      Documentation: html: show sections in the sidebar
      Documentation: html: adjust sidebar section titles styling

 Documentation/index.rst                |  8 ++++++++
 Documentation/sphinx-static/custom.css | 12 ++++++++++++
 2 files changed, 20 insertions(+)
---
base-commit: 075b74841bd0065a3bda3440873c747938e69b68
change-id: 20260723-show-sections-in-sidebar-b7f9aadf540e

Antonin Godard <antonin.godard@bootlin.com> writes:

> 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.
>
> Additionally, make the section titles in the sidebar bold to make them
> stand-out.
>
> This makes the overall structure of the documentation clearer from the
> sidebar directly.
>
> PS: This is how I've implemented this in the Yocto Project
> documentation[1] where I faced the same issue. See also the index.rst
> file[2] (which was by the way inspired by the kernel's own index.rst)
> and CSS addition[3].
>
> [1]: https://docs.yoctoproject.org/dev/
> [2]: https://git.yoctoproject.org/yocto-docs/tree/documentation/index.rst
> [3]: https://git.yoctoproject.org/yocto-docs/tree/documentation/sphinx-static/theme_overrides.css#n106
>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
> Changes in v2:
> - Apply RB and TB from Randy on patch 1/2.
> - Remove whitespace before section title and first subsection.
> - Link to v1: https://patch.msgid.link/20260803-show-sections-in-sidebar-v1-0-b4fdc847525d@bootlin.com

You didn't answer my question about the PDF build.  It's easy to break
that build, and easy to forget to check it...trust me, I know.  I did
check it, and it all seems fine.

So the patches are applied, thanks.  I did tweak the CSS slightly:

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 34aaa424a75c..6c03dca44c82 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -87,7 +87,8 @@ section#the-linux-kernel-documentation p.caption { display: none; }
  * Make section titles bold in the sidebar, and decrease their bottom margin to
  * group them with their subsections.
  */
-div.sphinxsidebar p.caption { font-weight: bold; margin-bottom: -10px; }
+div.sphinxsidebar p.caption { font-weight: bold; margin-bottom: 0; }
+div.sphinxsidebar p.caption + ul { margin-top: 0; }
 
 /*
  * The CSS magic to toggle the contents on small screens.

This way more directly expresses the intent, and will (hopefully) cause
things to continue to work properly in the face of an Alabaster version
that changes the margins.

Thanks,

jon

On Wed Aug 5, 2026 at 9:41 PM CEST, Jonathan Corbet wrote:
> Antonin Godard <antonin.godard@bootlin.com> writes:
>
>> 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.
>>
>> Additionally, make the section titles in the sidebar bold to make them
>> stand-out.
>>
>> This makes the overall structure of the documentation clearer from the
>> sidebar directly.
>>
>> PS: This is how I've implemented this in the Yocto Project
>> documentation[1] where I faced the same issue. See also the index.rst
>> file[2] (which was by the way inspired by the kernel's own index.rst)
>> and CSS addition[3].
>>
>> [1]: https://docs.yoctoproject.org/dev/
>> [2]: https://git.yoctoproject.org/yocto-docs/tree/documentation/index.rst
>> [3]: https://git.yoctoproject.org/yocto-docs/tree/documentation/sphinx-static/theme_overrides.css#n106
>>
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>> Changes in v2:
>> - Apply RB and TB from Randy on patch 1/2.
>> - Remove whitespace before section title and first subsection.
>> - Link to v1: https://patch.msgid.link/20260803-show-sections-in-sidebar-v1-0-b4fdc847525d@bootlin.com
>
> You didn't answer my question about the PDF build.  It's easy to break
> that build, and easy to forget to check it...trust me, I know.  I did
> check it, and it all seems fine.

Perhaps you missed my answer on v1:
https://lore.kernel.org/r/DKG7P6BAPV5Q.1UO4XWHZT8H15@bootlin.com

Thanks for taking the time to check the PDF build.

> So the patches are applied, thanks.  I did tweak the CSS slightly:
>
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index 34aaa424a75c..6c03dca44c82 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -87,7 +87,8 @@ section#the-linux-kernel-documentation p.caption { display: none; }
>   * Make section titles bold in the sidebar, and decrease their bottom margin to
>   * group them with their subsections.
>   */
> -div.sphinxsidebar p.caption { font-weight: bold; margin-bottom: -10px; }
> +div.sphinxsidebar p.caption { font-weight: bold; margin-bottom: 0; }
> +div.sphinxsidebar p.caption + ul { margin-top: 0; }
>  
>  /*
>   * The CSS magic to toggle the contents on small screens.
>
> This way more directly expresses the intent, and will (hopefully) cause
> things to continue to work properly in the face of an Alabaster version
> that changes the margins.

This looks better indeed :)

Antonin

"Antonin Godard" <antonin.godard@bootlin.com> writes:

>> You didn't answer my question about the PDF build.  It's easy to break
>> that build, and easy to forget to check it...trust me, I know.  I did
>> check it, and it all seems fine.
>
> Perhaps you missed my answer on v1:
> https://lore.kernel.org/r/DKG7P6BAPV5Q.1UO4XWHZT8H15@bootlin.com

Indeed I did, sorry.

Thanks,

jon