alabaster 0.6.3

Theme location

The function alabaster.get_path dynamically returns Alabaster’s install location, ensuring that Sphinx can find and load it regardless of where/how you installed Alabaster. Using it is highly recommended.

If you’ve manually installed Alabaster 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.

Sidebars

Feel free to adjust html_sidebars as desired - the theme is designed assuming you’ll always have about.html activated, but otherwise it doesn’t care much.

• See the Sphinx docs for details on how this setting behaves.

• Alabaster provides about.html (logo, github buttom + blurb), donate.html (Gratipay blurb/button) and navigation.html (a more flexible version of the builtin localtoc/globaltoc templates). searchbox.html comes with Sphinx itself.

Images

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 for ‘html_static_path’):

html_static_path = ['_static']

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 text (if there is any.)

• 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:

    • 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.

• travis_button: true, false or a Github-style "account/repo" string - used to display a Travis-CI build status button in the sidebar. If true, uses your github_(user|repo) settings; defaults to false.

• gratipay_user: Set to your Gratipay username if you want a Gratipay ‘Donate’ section in your sidebar.

  • This used to be gittip_user before that service changed its name to Gratipay; we’ve left the old setting in place as an alias for backwards compatibility reasons. It may be removed in the future.

  • If both options are given, gratipay_user wins.

• analytics_id: Set to your Google 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.

• sidebar_includehidden: Boolean determining whether the TOC sidebar should include hidden Sphinx toctree elements. Defaults to true so you can use :hidden: in your index page’s root toctree & avoid having 2x copies of your navigation on your landing page.

• show_powered_by: Boolean controlling display of the Powered by Sphinx N.N.N. & Alabaster M.M.M section of the footer. When True, is displayed next to the copyright information; when False, is hidden.

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.

• pink_1: Light pink.

• pink_2: Medium pink.

• 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.

• warn_bg: Background of .. warn:: blocks. Defaults to pink_1.

• warn_border: Border of same. Defaults to pink_2.

• 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.