Allabaster: a Sphinx theme

Warning

This page is not reworked yet, and copied from Alabaster.

Allabaster is embeddable Alabaster

Changes from Alabaster

  • All these fancy sidebars and footers were stripped down, as well, as html head and body tags. Now theme generates not complete html pages, but html fragments. It’s intended usage – to insert these fragments into other html pages.
  • CSS code was modified to decrease chance of interference with css rules of the main site.
  • Breadcrumbs were added to simplify navigation.

Alabaster is a visually (c)lean, responsive, configurable theme for the Sphinx documentation system. It is Python 2+3 compatible.

It began as a third-party theme, and is still maintained separately, but as of Sphinx 1.3, Alabaster is an install-time dependency of Sphinx and is selected as the default theme.

Live examples of this theme can be seen on this project’s own website, paramiko.org, fabfile.org and pyinvoke.org.

For more documentation, please see http://alabaster.readthedocs.io.

Note

You can install the development version via pip install alabaster==dev.

Features

  • Easy ability to install/use as a Python package (tip o’ the hat to Dave & Eric’s sphinx_rtd_theme for showing the way);
  • Style tweaks compared to the source themes, such as better code-block alignment, Github button placement, page source link moved to footer, improved (optional) related-items sidebar item, and many more;
  • Many customization hooks, including toggle of various sidebar & footer components; header/link/etc color control; etc;
  • Improved documentation for all customizations (pre-existing & new).

Project background

Alabaster is a modified (with permission) version of Kenneth Reitz’s “krTheme” Sphinx theme (it’s the one used in his Requests project). Kenneth’s theme was itself originally based on Armin Ronacher’s Flask theme. Many thanks to both for their hard work.

Implementation notes

  • Fabric #419 contains a lot of general exposition & thoughts as I developed Alabaster, specifically with a mind towards using it on two nearly identical ‘sister’ sites (single-version www ‘info’ site & versioned API docs site).
  • Alabaster includes/requires a tiny Sphinx extension on top of the theme itself; this is just so we can inject dynamic metadata (like Alabaster’s own version number) into template contexts. It doesn’t add any additional directives or the like, at least not yet.