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

[Jonathan Corbet <corbet@lwn.net>]

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