qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Thomas Lamprecht
Subject: Re: [PATCH v5] sphinx: adopt kernel readthedoc theme
Date: Tue, 23 Mar 2021 13:25:34 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:87.0) Gecko/20100101 Thunderbird/87.0

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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]