<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>HTML theming support — Sphinx v1.0.7 documentation</title>
<link rel="stylesheet" href="_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.0.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx v1.0.7 documentation"
href="_static/opensearch.xml"/>
<link rel="top" title="Sphinx v1.0.7 documentation" href="index.html" />
<link rel="next" title="Templating" href="templating.html" />
<link rel="prev" title="The build configuration file" href="config.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="templating.html" title="Templating"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="config.html" title="The build configuration file"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</a>
»</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">HTML theming support</a><ul>
<li><a class="reference internal" href="#using-a-theme">Using a theme</a></li>
<li><a class="reference internal" href="#builtin-themes">Builtin themes</a></li>
<li><a class="reference internal" href="#creating-themes">Creating themes</a><ul>
<li><a class="reference internal" href="#templating">Templating</a></li>
<li><a class="reference internal" href="#static-templates">Static templates</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="config.html"
title="previous chapter">The build configuration file</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="templating.html"
title="next chapter">Templating</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/theming.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="html-theming-support">
<h1>HTML theming support<a class="headerlink" href="#html-theming-support" title="Permalink to this headline">¶</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version 0.6.</span></p>
<p>Sphinx supports changing the appearance of its HTML output via <em>themes</em>. A
theme is a collection of HTML templates, stylesheet(s) and other static files.
Additionally, it has a configuration file which specifies from which theme to
inherit, which highlighting style to use, and what options exist for customizing
the theme’s look and feel.</p>
<p>Themes are meant to be project-unaware, so they can be used for different
projects without change.</p>
<div class="section" id="using-a-theme">
<h2>Using a theme<a class="headerlink" href="#using-a-theme" title="Permalink to this headline">¶</a></h2>
<p>Using an existing theme is easy. If the theme is builtin to Sphinx, you only
need to set the <a class="reference internal" href="config.html#confval-html_theme"><tt class="xref std std-confval docutils literal"><span class="pre">html_theme</span></tt></a> config value. With the
<a class="reference internal" href="config.html#confval-html_theme_options"><tt class="xref std std-confval docutils literal"><span class="pre">html_theme_options</span></tt></a> config value you can set theme-specific options
that change the look and feel. For example, you could have the following in
your <tt class="file docutils literal"><span class="pre">conf.py</span></tt>:</p>
<div class="highlight-python"><pre>html_theme = "default"
html_theme_options = {
"rightsidebar": "true",
"relbarbgcolor": "black"
}</pre>
</div>
<p>That would give you the default theme, but with a sidebar on the right side and
a black background for the relation bar (the bar with the navigation links at
the page’s top and bottom).</p>
<p>If the theme does not come with Sphinx, it can be in two forms: either a
directory (containing <tt class="file docutils literal"><span class="pre">theme.conf</span></tt> and other needed files), or a zip file
with the same contents. Either of them must be put where Sphinx can find it;
for this there is the config value <a class="reference internal" href="config.html#confval-html_theme_path"><tt class="xref std std-confval docutils literal"><span class="pre">html_theme_path</span></tt></a>. It gives a list
of directories, relative to the directory containing <tt class="file docutils literal"><span class="pre">conf.py</span></tt>, that can
contain theme directories or zip files. For example, if you have a theme in the
file <tt class="file docutils literal"><span class="pre">blue.zip</span></tt>, you can put it right in the directory containing
<tt class="file docutils literal"><span class="pre">conf.py</span></tt> and use this configuration:</p>
<div class="highlight-python"><pre>html_theme = "blue"
html_theme_path = ["."]</pre>
</div>
</div>
<div class="section" id="builtin-themes">
<span id="id1"></span><h2>Builtin themes<a class="headerlink" href="#builtin-themes" title="Permalink to this headline">¶</a></h2>
<table border="1" class="right docutils">
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody valign="top">
<tr><td><strong>Theme overview</strong></td>
<td> </td>
</tr>
<tr><td><p class="first"><img alt="default" src="_images/default.png" /></p>
<p class="last"><em>default</em></p>
</td>
<td><p class="first"><img alt="sphinxdoc" src="_images/sphinxdoc.png" /></p>
<p class="last"><em>sphinxdoc</em></p>
</td>
</tr>
<tr><td><p class="first"><img alt="scrolls" src="_images/scrolls.png" /></p>
<p class="last"><em>scrolls</em></p>
</td>
<td><p class="first"><img alt="agogo" src="_images/agogo.png" /></p>
<p class="last"><em>agogo</em></p>
</td>
</tr>
<tr><td><p class="first"><img alt="traditional" src="_images/traditional.png" /></p>
<p class="last"><em>traditional</em></p>
</td>
<td><p class="first"><img alt="nature" src="_images/nature.png" /></p>
<p class="last"><em>nature</em></p>
</td>
</tr>
<tr><td><p class="first"><img alt="haiku" src="_images/haiku.png" /></p>
<p class="last"><em>haiku</em></p>
</td>
<td> </td>
</tr>
</tbody>
</table>
<p>Sphinx comes with a selection of themes to choose from.</p>
<p>These themes are:</p>
<ul>
<li><p class="first"><strong>basic</strong> – This is a basically unstyled layout used as the base for the
other themes, and usable as the base for custom themes as well. The HTML
contains all important elements like sidebar and relation bar. There is one
option (which is inherited by the other themes):</p>
<ul class="simple">
<li><strong>nosidebar</strong> (true or false): Don’t include the sidebar. Defaults to
false.</li>
</ul>
</li>
<li><p class="first"><strong>default</strong> – This is the default theme, which looks like <a class="reference external" href="http://docs.python.org/">the Python
documentation</a>. It can be customized via these
options:</p>
<ul class="simple">
<li><strong>rightsidebar</strong> (true or false): Put the sidebar on the right side.
Defaults to false.</li>
<li><strong>stickysidebar</strong> (true or false): Make the sidebar “fixed” so that it
doesn’t scroll out of view for long body content. This may not work well
with all browsers. Defaults to false.</li>
<li><strong>collapsiblesidebar</strong> (true or false): Add an <em>experimental</em> JavaScript
snippet that makes the sidebar collapsible via a button on its side.
<em>Doesn’t work together with “rightsidebar” or “stickysidebar”.</em> Defaults to
false.</li>
<li><strong>externalrefs</strong> (true or false): Display external links differently from
internal links. Defaults to false.</li>
</ul>
<p>There are also various color and font options that can change the color scheme
without having to write a custom stylesheet:</p>
<ul class="simple">
<li><strong>footerbgcolor</strong> (CSS color): Background color for the footer line.</li>
<li><strong>footertextcolor</strong> (CSS color): Text color for the footer line.</li>
<li><strong>sidebarbgcolor</strong> (CSS color): Background color for the sidebar.</li>
<li><strong>sidebarbtncolor</strong> (CSS color): Background color for the sidebar collapse
button (used when <em>collapsiblesidebar</em> is true).</li>
<li><strong>sidebartextcolor</strong> (CSS color): Text color for the sidebar.</li>
<li><strong>sidebarlinkcolor</strong> (CSS color): Link color for the sidebar.</li>
<li><strong>relbarbgcolor</strong> (CSS color): Background color for the relation bar.</li>
<li><strong>relbartextcolor</strong> (CSS color): Text color for the relation bar.</li>
<li><strong>relbarlinkcolor</strong> (CSS color): Link color for the relation bar.</li>
<li><strong>bgcolor</strong> (CSS color): Body background color.</li>
<li><strong>textcolor</strong> (CSS color): Body text color.</li>
<li><strong>linkcolor</strong> (CSS color): Body link color.</li>
<li><strong>visitedlinkcolor</strong> (CSS color): Body color for visited links.</li>
<li><strong>headbgcolor</strong> (CSS color): Background color for headings.</li>
<li><strong>headtextcolor</strong> (CSS color): Text color for headings.</li>
<li><strong>headlinkcolor</strong> (CSS color): Link color for headings.</li>
<li><strong>codebgcolor</strong> (CSS color): Background color for code blocks.</li>
<li><strong>codetextcolor</strong> (CSS color): Default text color for code blocks, if not
set differently by the highlighting style.</li>
<li><strong>bodyfont</strong> (CSS font-family): Font for normal text.</li>
<li><strong>headfont</strong> (CSS font-family): Font for headings.</li>
</ul>
</li>
<li><p class="first"><strong>sphinxdoc</strong> – The theme used for this documentation. It features a sidebar
on the right side. There are currently no options beyond <em>nosidebar</em>.</p>
</li>
<li><p class="first"><strong>scrolls</strong> – A more lightweight theme, based on <a class="reference external" href="http://jinja.pocoo.org/2/documentation/">the Jinja documentation</a>. The following color options are
available:</p>
<ul class="simple">
<li><strong>headerbordercolor</strong></li>
<li><strong>subheadlinecolor</strong></li>
<li><strong>linkcolor</strong></li>
<li><strong>visitedlinkcolor</strong></li>
<li><strong>admonitioncolor</strong></li>
</ul>
</li>
<li><p class="first"><strong>agogo</strong> – A theme created by Andi Albrecht. The following options are
supported:</p>
<ul class="simple">
<li><strong>bodyfont</strong> (CSS font family): Font for normal text.</li>
<li><strong>headerfont</strong> (CSS font family): Font for headings.</li>
<li><strong>pagewidth</strong> (CSS length): Width of the page content, default 70em.</li>
<li><strong>documentwidth</strong> (CSS length): Width of the document (without sidebar),
default 50em.</li>
<li><strong>sidebarwidth</strong> (CSS length): Width of the sidebar, default 20em.</li>
<li><strong>bgcolor</strong> (CSS color): Background color.</li>
<li><strong>headerbg</strong> (CSS value for “background”): background for the header area,
default a grayish gradient.</li>
<li><strong>footerbg</strong> (CSS value for “background”): background for the footer area,
default a light gray gradient.</li>
<li><strong>linkcolor</strong> (CSS color): Body link color.</li>
<li><strong>headercolor1</strong>, <strong>headercolor2</strong> (CSS color): colors for <h1> and <h2>
headings.</li>
<li><strong>headerlinkcolor</strong> (CSS color): Color for the backreference link in
headings.</li>
<li><strong>textalign</strong> (CSS <em>text-align</em> value): Text alignment for the body, default
is <tt class="docutils literal"><span class="pre">justify</span></tt>.</li>
</ul>
</li>
<li><p class="first"><strong>nature</strong> – A greenish theme. There are currently no options beyond
<em>nosidebar</em>.</p>
</li>
<li><p class="first"><strong>haiku</strong> – A theme without sidebar inspired by the <a class="reference external" href="http://www.haiku-os.org/docs/userguide/en/contents.html">Haiku OS user guide</a>. The following
options are supported:</p>
<ul class="simple">
<li><strong>full_logo</strong> (true or false, default false): If this is true, the header
will only show the <a class="reference internal" href="config.html#confval-html_logo"><tt class="xref std std-confval docutils literal"><span class="pre">html_logo</span></tt></a>. Use this for large logos. If this
is false, the logo (if present) will be shown floating right, and the
documentation title will be put in the header.</li>
<li><strong>textcolor</strong>, <strong>headingcolor</strong>, <strong>linkcolor</strong>, <strong>visitedlinkcolor</strong>,
<strong>hoverlinkcolor</strong> (CSS colors): Colors for various body elements.</li>
</ul>
</li>
<li><p class="first"><strong>traditional</strong> – A theme resembling the old Python documentation. There are
currently no options beyond <em>nosidebar</em>.</p>
</li>
<li><p class="first"><strong>epub</strong> – A theme for the epub builder. There are currently no options.
This theme tries to save visual space which is a sparse resource on ebook
readers.</p>
</li>
</ul>
</div>
<div class="section" id="creating-themes">
<h2>Creating themes<a class="headerlink" href="#creating-themes" title="Permalink to this headline">¶</a></h2>
<p>As said, themes are either a directory or a zipfile (whose name is the theme
name), containing the following:</p>
<ul class="simple">
<li>A <tt class="file docutils literal"><span class="pre">theme.conf</span></tt> file, see below.</li>
<li>HTML templates, if needed.</li>
<li>A <tt class="docutils literal"><span class="pre">static/</span></tt> directory containing any static files that will be copied to the
output statid directory on build. These can be images, styles, script files.</li>
</ul>
<p>The <tt class="file docutils literal"><span class="pre">theme.conf</span></tt> file is in INI format <a class="footnote-reference" href="#id3" id="id2">[1]</a> (readable by the standard
Python <tt class="xref py py-mod docutils literal"><span class="pre">ConfigParser</span></tt> module) and has the following structure:</p>
<div class="highlight-ini"><pre>[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
[options]
variable = default value</pre>
</div>
<ul class="simple">
<li>The <strong>inherit</strong> setting gives the name of a “base theme”, or <tt class="docutils literal"><span class="pre">none</span></tt>. The
base theme will be used to locate missing templates (most themes will not have
to supply most templates if they use <tt class="docutils literal"><span class="pre">basic</span></tt> as the base theme), its options
will be inherited, and all of its static files will be used as well.</li>
<li>The <strong>stylesheet</strong> setting gives the name of a CSS file which will be
referenced in the HTML header. If you need more than one CSS file, either
include one from the other via CSS’ <tt class="docutils literal"><span class="pre">@import</span></tt>, or use a custom HTML template
that adds <tt class="docutils literal"><span class="pre"><link</span> <span class="pre">rel="stylesheet"></span></tt> tags as necessary. Setting the
<a class="reference internal" href="config.html#confval-html_style"><tt class="xref std std-confval docutils literal"><span class="pre">html_style</span></tt></a> config value will override this setting.</li>
<li>The <strong>pygments_style</strong> setting gives the name of a Pygments style to use for
highlighting. This can be overridden by the user in the
<a class="reference internal" href="config.html#confval-pygments_style"><tt class="xref std std-confval docutils literal"><span class="pre">pygments_style</span></tt></a> config value.</li>
<li>The <strong>options</strong> section contains pairs of variable names and default values.
These options can be overridden by the user in <a class="reference internal" href="config.html#confval-html_theme_options"><tt class="xref std std-confval docutils literal"><span class="pre">html_theme_options</span></tt></a>
and are accessible from all templates as <tt class="docutils literal"><span class="pre">theme_<name></span></tt>.</li>
</ul>
<div class="section" id="templating">
<h3>Templating<a class="headerlink" href="#templating" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="templating.html"><em>guide to templating</em></a> is helpful if you want to write your
own templates. What is important to keep in mind is the order in which Sphinx
searches for templates:</p>
<ul class="simple">
<li>First, in the user’s <tt class="docutils literal"><span class="pre">templates_path</span></tt> directories.</li>
<li>Then, in the selected theme.</li>
<li>Then, in its base theme, its base’s base theme, etc.</li>
</ul>
<p>When extending a template in the base theme with the same name, use the theme
name as an explicit directory: <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">"basic/layout.html"</span> <span class="pre">%}</span></tt>. From a
user <tt class="docutils literal"><span class="pre">templates_path</span></tt> template, you can still use the “exclamation mark”
syntax as described in the templating document.</p>
</div>
<div class="section" id="static-templates">
<h3>Static templates<a class="headerlink" href="#static-templates" title="Permalink to this headline">¶</a></h3>
<p>Since theme options are meant for the user to configure a theme more easily,
without having to write a custom stylesheet, it is necessary to be able to
template static files as well as HTML files. Therefore, Sphinx supports
so-called “static templates”, like this:</p>
<p>If the name of a file in the <tt class="docutils literal"><span class="pre">static/</span></tt> directory of a theme (or in the user’s
static path, for that matter) ends with <tt class="docutils literal"><span class="pre">_t</span></tt>, it will be processed by the
template engine. The <tt class="docutils literal"><span class="pre">_t</span></tt> will be left from the final file name. For
example, the <em>default</em> theme has a file <tt class="docutils literal"><span class="pre">static/default.css_t</span></tt> which uses
templating to put the color options into the stylesheet. When a documentation
is built with the default theme, the output directory will contain a
<tt class="docutils literal"><span class="pre">_static/default.css</span></tt> file where all template tags have been processed.</p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>It is not an executable Python file, as opposed to <tt class="file docutils literal"><span class="pre">conf.py</span></tt>,
because that would pose an unnecessary security risk if themes are
shared.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="templating.html" title="Templating"
>next</a> |</li>
<li class="right" >
<a href="config.html" title="The build configuration file"
>previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</a>
»</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
119
