Installation¶
Warning
This page is not reworked yet, and copied from Alabaster.
The bare minimum required to install Alabaster is as follows:
If you’re on Sphinx 1.2 or older:
pip install alabaster
or equivalent.Add the following to your
conf.py
so Alabaster’s theme location & mini-extension are located & loaded:import alabaster html_theme_path = [alabaster.get_path()] extensions = ['alabaster'] html_theme = 'alabaster'
If you’ve installed Alabaster by hand (without using
pip
) and/or are doing funky things to your PYTHONPATH, you may need to replace thealabaster.get_path()
call with your own explicit string, as per the Sphinx config docs.
If you have Sphinx 1.3 or above:
You already have Alabaster installed as a dependency! No need to manually install it or explicitly load it.
Note
If you distribute your documentation via the excellent Read the Docs, you may need to explicitly enable Alabaster (as RTD defaults to using its own theme) by adding this line to your
conf.py
:html_theme = ['alabaster']
Either way, add an explicit
html_sidebars
setting so Alabaster’s customized sidebar templates are loaded:html_sidebars = { '**': [ 'about.html', 'navigation.html', 'relations.html', 'searchbox.html', 'donate.html', ] }
That’s it! You now have the standard Alabaster theme set up. Read on for more core configuration concerns, or see Customization for feature/style options.
Sidebars¶
Feel free to adjust html_sidebars
as desired - the theme is designed
assuming you’ll always have about.html
activated, but otherwise it doesn’t
care much.
- See the Sphinx docs for details on how this setting behaves.
- Alabaster provides
about.html
(logo, github button + blurb),donate.html
(Gratipay blurb/button) andnavigation.html
(a more flexible version of the builtinlocaltoc
/globaltoc
templates).searchbox.html
comes with Sphinx itself.
Static path for images and/or custom stylesheet¶
If you’re using any of the image-related options listed on Customization
(logo
or touch-icon
) or a custom stylesheet,
you’ll also want to tell Sphinx where to get these files from. If so, add a
line like this (changing the path if necessary; see the Sphinx docs for
‘html_static_path’) to your conf.py
:
html_static_path = ['_static']