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

On 8/3/26 12:13 PM, Jonathan Corbet wrote:
> Antonin Godard <[email protected]> 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 <[email protected]>
>> ---
>> 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