Installation

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 the alabaster.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.

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']