skip to navigation
skip to content

Not Logged In

alabaster 0.1.0

A configurable sidebar-enabled Sphinx theme

Latest Version: 0.6.0

# Alabaster: a Sphinx theme

This theme is a modified "Kr" Sphinx theme from @kennethreitz (especially as
used in his [Requests](https://python-requests.org) project), which was itself
originally based on @mitsuhiko's theme used for
[Flask](http://flask.pocoo.org/) & related projects.

Features (compared to Kenneth's theme):

* Easy ability to install/use as a Python package (tip o' the hat to [Dave &
  Eric's sphinx_rtd_theme](https://github.com/snide/sphinx_rtd_theme) for
  showing the way);
* Style tweaks, such as better code-block alignment, Gittip button placement,
  page source link moved to footer, etc;
* Additional customization hooks, such as header/link/etc colors;
* Improved documentation for all customizations (pre-existing & new).

To use:

1. `pip install alabaster` (or equivalent command)
1. Enable the 'alabaster' theme in your `conf.py`:

   ```python
   import alabaster

   html_theme_path = [alabaster.get_path()]
   html_theme = 'alabaster'
   html_sidebars = {
       'index': [
           'about.html', 'searchbox.html', 'donate.html',
       ],
       '**': [
           'about.html', 'localtoc.html', 'searchbox.html', 'donate.html',
       ]
   }
   ```

    * Modify the call to `abspath` if your `_themes` folder doesn't live right
    next to your `conf.py`.
    * Feel free to adjust `html_sidebars` as desired - the theme is designed
    assuming you'll have `about.html` activated, but otherwise it doesn't care
    much.
        * See [the Sphinx
        docs](http://sphinx-doc.org/config.html#confval-html_sidebars) for
        details on how this setting behaves.
        * Alabaster provides `about.html` (logo, github buttom + blurb) and
        `donate.html` (Gittip blurb/button); the others listed come from Sphinx
        itself. We split out `donate.html` so it could be moved around the
        sidebar with more freedom.

1. If you're using either of the image-related options outlined below (logo or
   touch-icon), you'll also want to tell Sphinx where to get your images from.
   If so, add a line like this (changing the path if necessary; see [the Sphinx
   docs](http://sphinx-doc.org/config.html?highlight=static#confval-html_static_path)):

   ```python
   html_static_path = ['_static']
   ```

1. Add one more section to `conf.py` setting one or more theme options, like in
   this example (*note*: snippet doesn't include all possible options, see
   following list!):

   ```python
   html_theme_options = {
       'logo': 'logo.png',
       'github_user': 'bitprophet',
       'github_repo': 'alabaster',
   }
   ```

   The available theme options (which are all optional) are as follows:

   **Variables and feature toggles**

   * `logo`: Relative path (from `$PROJECT/_static/`) to a logo image, which
   will appear in the upper left corner above the name of the project.
      * If `logo` is not set, your `project` name setting (from the top level
      Sphinx config) will be used in a text header instead. This preserves a
      link back to your homepage from inner doc pages.
   * `logo_name`: Set to `true` to insert your site's `project` name under the
   logo image as text. Useful if your logo doesn't include the project name
   itself. Defaults to `false`.
   * `description`: Text blurb about your project, to appear under the logo.
   * `github_user`, `github_repo`: Used by `github_button` and `github_banner`
   (see below); does nothing if both of those are set to `false`.
   * `github_button`: `true` or `false` (default: `true`) - whether to link to
   your Github.
       * If `true`, requires that you set `github_user` and `github_repo`.
       * See also these other related options, which behave as described
   in [Github Buttons' README](https://github.com/mdo/github-buttons#usage):
          * `github_button_type`: Defaults to `watch`.
          * `github_button_count`: Defaults to `true`.
   * `github_banner`: `true` or `false` (default: `false`) - whether to apply a
   'Fork me on Github' banner in the top right corner of the page.
       * If `true`, requires that you set `github_user` and `github_repo`.
   * `gittip_user`: Set to your [Gittip](https://gittip.com) username if you
   want a Gittip 'Donate' section in your sidebar.
   * `analytics_id`: Set to your [Google
   Analytics](http://www.google.com/analytics/) ID (e.g. `UA-#######-##`) to
   enable tracking.
   * `touch_icon`: Path to an image (as with `logo`, relative to
   `$PROJECT/_static/`) to be used for an iOS application icon, for when pages
   are saved to an iOS device's home screen via Safari.

   **Style colors**

   These should be fully qualified CSS color specifiers such as `#004B6B` or
   `#444`. The first few items in the list are "global" colors used as defaults
   for many of the others; update these to make sweeping changes to the
   colorscheme. The more granular settings can be used to override as needed.

   * `gray_1`: Medium gray.
   * `gray_2`: Light gray.
   * `body_text`: Main content text.
   * `footer_text`: Footer text (includes links.)
   * `link`: Non-hovered body links.
   * `link_hover`: Body links, hovered.
   * `sidebar_header`: Sidebar headers. Defaults to `gray_1`.
   * `sidebar_text`: Sidebar paragraph text.
   * `sidebar_link`: Sidebar links (there is no hover variant.) Applies to both
   header & text links. Defaults to `gray_1.
   * `sidebar_link_underscore`: Sidebar links' underline (technically a
   bottom-border.)
   * `sidebar_search_button`: Background color of the search field's 'Go'
   button.
   * `sidebar_list`: Foreground color of sidebar list bullets & unlinked text.
   * `anchor`: Foreground color of section anchor links (the 'paragraph' symbol
   that shows up when you mouseover page section headers.)
   * `anchor_hover_fg`: Foreground color of section anchor links (as above)
   when moused over. Defaults to `gray_1.
   * `anchor_hover_bg`: Background color of above.
   * `note_bg`: Background of `.. note::` blocks. Defaults to `gray_2`.
   * `note_border`: Border of same.
   * `footnote_bg`: Background of footnote blocks.
   * `footnote_border`: Border of same. Defaults to `gray_2`.
   * `pre_bg`: Background of preformatted text blocks (including code
   snippets.) Defaults to `gray_2`.
   * `narrow_sidebar_bg`: Background of 'sidebar' when narrow window forces it
   to the bottom of the page.
   * `narrow_sidebar_fg`: Text color of same.
   * `narrow_sidebar_link`: Link color of same.
 
File Type Py Version Uploaded on Size
alabaster-0.1.0.tar.gz (md5) Source 2014-01-10 9KB
  • Downloads (All Versions):
  • 560 downloads in the last day
  • 1874 downloads in the last week
  • 4351 downloads in the last month