alabaster 0.2.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 and Github 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 = {
'**': [
'about.html', 'navigation.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),
`donate.html` (Gittip blurb/button) and `navigation.html` (a more
flexible version of the builtin `localtoc`/`globaltoc` templates); the
others listed come from Sphinx itself.

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`.
* `logo_text_align`: Which CSS `text-align` value to use for logo
replacement text (thus only applicable of `logo` is unset.) Defaults to
`left`.
* `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.
* `extra_nav_links`: Dictionary mapping link names to link targets; these
will be added in a UL below the main sidebar navigation (provided you've
enabled `navigation.html`.) Useful for static links outside your Sphinx
doctree.

**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`: Dark gray.
* `gray_2`: Light gray.
* `gray_3`: Medium 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.
* `sidebar_hr`: Color of sidebar horizontal rule dividers. Defaults to
`gray_3`.
* `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. Defaults to `gray_3`.

## Further reading

* [Fabric #419](https://github.com/fabric/fabric/issues/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).