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

[PATCH 0/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 sidenbar, 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>
---
Antonin Godard (2):
      Documentation: html: show sections in the sidebar
      Documentation: html: make sidebar section titles bold

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

[PATCH 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 sidenbar, but hide them from the
index page with a custom CSS addition.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 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

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

[Randy Dunlap]

On 8/3/26 7:35 AM, Antonin Godard wrote:
> 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 sidenbar, but hide them from the
> index page with a custom CSS addition.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Nice. I like it. Thanks.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  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.
>   */
> 

-- 
~Randy

[PATCH 2/2] Documentation: html: make sidebar section titles bold

[Antonin Godard]

Now that section titles are displayed in the sidebar, make them bold to
have them stand out compared to the subsection titles.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 Documentation/sphinx-static/custom.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index 0576d4fcb2a3..3938daf410c3 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -81,6 +81,11 @@ div.kerneltoc li.current ul { background-color: white; }
  */
 section#the-linux-kernel-documentation p.caption { display: none; }
 
+/*
+ * Make section titles bold in the sidebar.
+ */
+div.sphinxsidebar p.caption { font-weight: bold; }
+
 /*
  * The CSS magic to toggle the contents on small screens.
  */

-- 
2.55.0

Re: [PATCH 2/2] Documentation: html: make sidebar section titles bold

[Randy Dunlap]

On 8/3/26 7:35 AM, Antonin Godard wrote:
> Now that section titles are displayed in the sidebar, make them bold to
> have them stand out compared to the subsection titles.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

LGTM. Thanks.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/sphinx-static/custom.css | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index 0576d4fcb2a3..3938daf410c3 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -81,6 +81,11 @@ div.kerneltoc li.current ul { background-color: white; }
>   */
>  section#the-linux-kernel-documentation p.caption { display: none; }
>  
> +/*
> + * Make section titles bold in the sidebar.
> + */
> +div.sphinxsidebar p.caption { font-weight: bold; }
> +
>  /*
>   * The CSS magic to toggle the contents on small screens.
>   */
> 

-- 
~Randy

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

[Jonathan Corbet]

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 sidenbar, 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>
> ---
> Antonin Godard (2):
>       Documentation: html: show sections in the sidebar
>       Documentation: html: make sidebar section titles bold
>
>  Documentation/index.rst                |  8 ++++++++
>  Documentation/sphinx-static/custom.css | 11 +++++++++++
>  2 files changed, 19 insertions(+)

This looks like it could be a nice improvement, but I have a couple of
thoughts...

- Did you check the PDF build to be sure that the captions don't intrude
  in some sort of obnoxious ways?

- I'd tweak the CSS to remove the white space below the section
  headings, just to bind them to their subsections properly.

Thanks,

jon

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

[Randy Dunlap]

On 8/3/26 12:13 PM, 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 sidenbar, 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>
>> ---
>> Antonin Godard (2):
>>       Documentation: html: show sections in the sidebar
>>       Documentation: html: make sidebar section titles bold
>>
>>  Documentation/index.rst                |  8 ++++++++
>>  Documentation/sphinx-static/custom.css | 11 +++++++++++
>>  2 files changed, 19 insertions(+)
> 
> This looks like it could be a nice improvement, but I have a couple of
> thoughts...
> 
> - Did you check the PDF build to be sure that the captions don't intrude
>   in some sort of obnoxious ways?
> 

I only checked html and epub output. I can't see that epub is affected.

On another note, it would be good to have the kernel version listed in
the epub book (output).

> - I'd tweak the CSS to remove the white space below the section
>   headings, just to bind them to their subsections properly.


-- 
~Randy

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

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

>> - Did you check the PDF build to be sure that the captions don't intrude
>>   in some sort of obnoxious ways?
>> 
>
> I only checked html and epub output. I can't see that epub is affected.

EPUB is HTML+CSS underneath, though, so I would expect to behave
similarly.  PDF, though, will lack the CSS trick used to disappear the
captions in the normal text.

Thanks,

jon

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

[Antonin Godard]

Hi Jonathan,

On Mon Aug 3, 2026 at 9:13 PM CEST, Jonathan Corbet wrote:
[...]
> This looks like it could be a nice improvement, but I have a couple of
> thoughts...
>
> - Did you check the PDF build to be sure that the captions don't intrude
>   in some sort of obnoxious ways?

It isn't a problem for the Yocto Project documentation PDF. You can have a look
at the current PDF for it (with the ":caption:" properties):
https://docs.yoctoproject.org/dev/_static/theyoctoproject.pdf

And here would be the equivalent PDF with the ":caption:" properties _removed_:
https://lufi.bootlin.com/r/JbwZLTrHzJ#s/bmg9ZecGftbwZjvfJzaeh/ustGIzT1mKYJf5Yayu8=

I can't spot any differences.

I'm struggling to get things right to build the PDF for the kernel docs, so I
wasn't able to test it :-/ If you have some container image that I could use, it
might help as it seems to be related to my host packages versions.

For ePUBs, as Randy mentioned, TOC is handled differently and the captions are
not seen in odd places.

> - I'd tweak the CSS to remove the white space below the section
>   headings, just to bind them to their subsections properly.

Got it, I added that for the next version.

Thanks!
Antonin