Re: [PATCH v5] sphinx: adopt kernel readthedoc theme

[Thomas Lamprecht <t.lamprecht@proxmox.com>]

On 23.03.21 12:53, marcandre.lureau@redhat.com wrote:
> From: Marc-André Lureau <marcandre.lureau@redhat.com>
> 

Just saw this patch by accident and as we also use the alabaster theme
for the Proxmox Backup project I wanted to share some insights from our
usage, as I checked that theme out closely a few months ago and did some
adaptions for, partially overlapping, short-comings we found.


> The default "alabaster" sphinx theme has a couple shortcomings:
> - the navbar moves along the page

That can be fixed with the following conf.py 'html_theme_options' setting:

'fixed_sidebar': True,

https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l161

> - the search bar is not always at the same place

Can be also addressed by setting 'html_sidebars' to a fixed order, e.g.:

html_sidebars = {
    '**': [
        'searchbox.html',
        'navigation.html',
        'relations.html',
    ]
}                 

Can also be customized for different pages, e.g., we do so for landing pages:

https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/conf.py;h=cfa4158d6b284172929785991f710d6237e9992c;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b#l188

I added also a short JS snipped to scroll the heading of the current chapter in
the sidebar TOC into view (adapted from rust book).
https://git.proxmox.com/?p=proxmox-backup.git;a=blob;f=docs/custom.js;h=7964b2cb0ea9433596845618f1679f1672ce38b8;hb=2ab2ca9c241f8315f51f9c74a50d7223c875a04b

If you want, you could check out the result at our hosted docs site:
https://pbs.proxmox.com/docs/managing-remotes.html

> - it lacks some contrast and colours

That is true, and IMO the rtd theme really uses a better colour palette,
especially for things like "Topic" blocks.
In fact we pondered switching over to rtd, so please don't see my mail
as me advertising that all issues can be fixed into alabaster, just wanted
to share what we did to overcome the first two short-comings mentioned here.

cheers,
Thomas