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

[Antonin Godard]

On Wed Aug 5, 2026 at 9:41 PM CEST, Jonathan Corbet wrote:
> Antonin Godard <antonin.godard@xxxxxxxxxxx> 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@xxxxxxxxxxx>
>> ---
>> 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@xxxxxxxxxxx
>
> 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@xxxxxxxxxxx

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