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

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 <[email protected]>

Nice. I like it. Thanks.

Reviewed-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>

> ---
>  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