alabaster
alabaster copied to clipboard
theme.conf should provide a sensible sidebars value
Since Sphinx 1.7 (https://github.com/sphinx-doc/sphinx/commit/b78f3090a05f38fb3beb14f7e716f1b26a2ff253), themes are expected to provide a sidebars value in theme.conf.
Currently alabaster does not and as it is used by default by Sphinx, this means default usage of sphinx-quickstart creates dysfunctional projects, requesting user manual intervention.
For example, the following at top of theme.conf
:
[theme]
inherit = basic
stylesheet = alabaster.css
pygments_style = alabaster.support.Alabaster
sidebars = about.html, navigation.html, relations.html, searchbox.html, donate.html
where I followed installation docs. Maybe the docs could state that by default CSS deactivates relations.html
?
Additional note: the fact that Sphinx in the 1.7.x series so far does not provide these values even in absence of the above line in Alabaster's theme.conf
is a bug (https://github.com/sphinx-doc/sphinx/issues/5066) which will get fixed in due time. Nevertheless, the above is needed because Sphinx at 2.0 will not provide anymore the correct defaults for Alabaster. (i.e. the currently buggy mechanism will anyhow have been removed by that release number).
I don't recall why we don't provide that by default, I assume there may be some specific (good) reason, but some research is necessary. Thanks for the report.
If nothing obvious turns up, yea, I agree this is an annoying high visibility wart and we should fix it, assuming we can do so without breaking anyone's existing installation. (AFAIK that should be fine, anyone already declaring sidebars
will have their value take precedence.)
Sorry. This is a bug of sphinx-core. We've failed to give default settings to alabaster. Now I'm trying to fix in on https://github.com/sphinx-doc/sphinx/pull/5094 .
About sidebars
option of theme.conf
was introduced since 1.7. It enables to define the default sidebars for the HTML theme. If alabaster support it, users will not need to add html_sidebar
setting to thier conf.py
.