What is Alabaster?¶

Alabaster is a visually (c)lean, responsive, configurable theme for theSphinx documentation system.It requires Python 3.10 or newer and Sphinx 6.2 or newer.

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

Live examples of this theme can be seen onthis project’s own website,paramiko.org,fabfile.org andpyinvoke.org.

For more documentation, please seehttps://alabaster.readthedocs.io/.

Features¶

• Easy ability to install/use as a Python package (tip o’ the hat toDave &Eric’s sphinx_rtd_theme forshowing the way);

• Style tweaks compared to the source themes, such as better code-blockalignment, 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 & footercomponents; header/link/etc color control; etc;

• Improved documentation for all customizations (pre-existing & new).

Project background¶

Alabaster is a modified (with permission) version ofKenneth Reitz’s“krTheme” Sphinx theme (it’s the one usedin hisRequests project). Kenneth’stheme was itself originally based on Armin Ronacher’sFlask theme. Many thanks to both for their hard work.

Implementation notes¶

• Fabric #419 contains a lot ofgeneral exposition & thoughts as I developed Alabaster, specifically with amind towards using it on two nearly identical ‘sister’ sites (single-versionwww ‘info’ site & versioned API docs site).

• Alabaster includes/requires a tiny Sphinx extension on top of the themeitself; this is just so we can inject dynamic metadata (like Alabaster’s ownversion number) into template contexts. It doesn’t add any additionaldirectives or the like, at least not yet.