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
Great, thanks for the tips.
However, the result doesn't seem as good on mobile yet.
> - 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.
Would you prefer QEMU to keep alabaster as a working and supported fallback for consistency? or you could maintain a downstream patch for your version perhaps?