merge with trunk

CHANGES

@@ -3,12 +3,14 @@ Release 1.0 (in development)
 
 * Support for docutils 0.4 has been removed.
 
+* Added new HTML theme ``agogo``, created by Andi Albrecht.
+
 * The ``toctree()`` callable in templates now has a ``maxdepth``
   keyword argument to control the depth of the generated tree.
 
-* Added Catalan translation, thanks to Pau Fernández.
+* Added new minimal theme called scrolls, created by Armin Ronacher.
 
-* Added new minimal theme called scrolls.
+* Added Catalan translation, thanks to Pau Fernández.
 
 * Added ``html_output_encoding`` config value.
 

doc/_templates/layout.html

@@ -1,5 +1,12 @@
 {% extends "!layout.html" %}
 
+{% block extrahead %}
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+{% endblock %}
+
 {% block rootrellink %}
         <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
         <li><a href="{{ pathto('contents') }}">Documentation</a>&raquo;</li>

doc/theming.rst

@@ -52,7 +52,33 @@ file :file:`blue.zip`, you can put it right in the directory containing
 Builtin themes
 --------------
 
-Sphinx comes with a selection of themes to choose from:
+.. cssclass:: right
+
++-----------------------------------------+
+| **Theme overview**                      |
++--------------------+--------------------+
+| |default|          | |sphinxdoc|        |
+|                    |                    |
+| *default*          | *sphinxdoc*        |
++--------------------+--------------------+
+| |scrolls|          | |agogo|            |
+|                    |                    |
+| *scrolls*          | *agogo*            |
++--------------------+--------------------+
+| |traditional|      |                    |
+|                    |                    |
+| *traditional*      |                    |
++--------------------+--------------------+
+
+.. |default|     image:: themes/default.png
+.. |sphinxdoc|   image:: themes/sphinxdoc.png
+.. |scrolls|     image:: themes/scrolls.png
+.. |agogo|       image:: themes/agogo.png
+.. |traditional| image:: themes/traditional.png
+
+Sphinx comes with a selection of themes to choose from.
+
+These themes are:
 
 * **basic** -- This is a basically unstyled layout used as the base for the
   *default* and *sphinxdoc* themes, and usable as the base for custom themes as
@@ -111,6 +137,26 @@ Sphinx comes with a selection of themes to choose from:
   - **visitedlinkcolor**
   - **admonitioncolor**
 
+* **agogo** -- A theme created by Andi Albrecht.  The following options are
+  supported:
+
+  - **bodyfont** (CSS font family): Font for normal text.
+  - **headerfont** (CSS font family): Font for headings.
+  - **pagewidth** (CSS length): Width of the page content, default 70em.
+  - **documentwidth** (CSS length): Width of the document (without sidebar),
+    default 50em.
+  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
+  - **bgcolor** (CSS color): Background color.
+  - **headerbg** (CSS value for "background"): background for the header area,
+    default a grayish gradient.
+  - **footerbg** (CSS value for "background"): background for the footer area,
+    default a light gray gradient.
+  - **linkcolor** (CSS color): Body link color.
+  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
+    headings.
+  - **headerlinkcolor** (CSS color): Color for the backreference link in
+    headings.
+
 * **traditional** -- A theme resembling the old Python documentation.  There are
   currently no options beyond *nosidebar*.
 

sphinx/themes/agogo/layout.html

@@ -0,0 +1,81 @@
+{% extends "basic/layout.html" %}
+
+{% block header %}
+    <div class="header-wrapper">
+      <div class="header">
+        {%- if logo %}
+          <p class="logo"><a href="{{ pathto(master_doc) }}">
+            <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+          </a></p>
+        {%- endif %}
+        {%- block headertitle %}
+	<h1><a href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a></h1>
+        {%- endblock %}
+	<div class="rel">
+          {%- for rellink in rellinks %}
+          <a href="{{ pathto(rellink[0]) }}" title="{{ rellink[1]|striptags }}"
+             {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
+          {%- if not loop.last %}{{ reldelim2 }}{% endif %}
+          {%- endfor %}
+	</div>
+       </div>
+    </div>
+{% endblock %}
+
+{% block content %}
+    <div class="content-wrapper">
+      <div class="content">
+	<div class="document">
+	  {%- block document %}
+            {{ super() }}
+	  {%- endblock %}
+	</div>
+	<div class="sidebar">
+          {%- block sidebartoc %}
+	  <h3>{{ _('Contents') }}</h3>
+	  {{ toctree() }}
+          {%- endblock %}
+          {%- block sidebarsearch %}
+	  <h3 style="margin-top: 1.5em;">{{ _('Search') }}</h3>
+	  <form class="search" action="{{ pathto('search') }}" 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>
+          {%- endblock %}
+	</div>
+	<div class="clearer"></div>
+      </div>
+    </div>
+{% endblock %}
+
+{% block footer %}
+    <div class="footer-wrapper">
+      <div class="footer">
+	<div class="left">
+	  {%- for rellink in rellinks %}
+          <a href="{{ pathto(rellink[0]) }}" title="{{ rellink[1]|striptags }}"
+             {{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
+          {%- if not loop.last %}{{ reldelim2 }}{% endif %}
+	  {%- endfor %}
+	  {%- if show_source and has_source and sourcename %}
+            <br/>
+            <a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+               rel="nofollow">{{ _('Show Source') }}</a>
+          {%- endif %}
+	</div>
+
+	<div class="right">
+          {{ super() }}
+	</div>
+	<div class="clearer"></div>
+      </div>
+    </div>
+{% endblock %}
+
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}

sphinx/themes/agogo/static/agogo.css_t

@@ -0,0 +1,336 @@
+* {
+  margin: 0px;
+  padding: 0px;
+}
+
+body {
+  font-family: {{ theme_bodyfont }};
+  line-height: 1.4em;
+  font-size: 14px;
+  color: black;
+  background-color: {{ theme_bgcolor }};
+}
+
+
+/* Page layout */
+
+div.header, div.content, div.footer {
+  width: {{ theme_pagewidth }};
+  margin-left: auto;
+  margin-right: auto;
+}
+
+div.header-wrapper {
+  background: {{ theme_headerbg }};
+  border-bottom: 3px solid #2e3436;
+}
+
+
+/* Default body styles */
+a {
+  text-decoration: none;
+  color: {{ theme_linkcolor }};
+}
+
+.clearer {
+  clear: both;
+}
+
+.left {
+  float: left;
+}
+
+.right {
+  float: right;
+}
+
+h1, h2, h3, h4 {
+  font-family: {{ theme_headerfont }};
+  font-weight: normal;
+  color: {{ theme_headercolor2 }};
+  margin-bottom: .8em;
+}
+
+h1 {
+  color: {{ theme_headercolor1 }};
+}
+
+h2 {
+  padding-bottom: .5em;
+  border-bottom: 1px solid {{ theme_headercolor2 }};
+}
+
+a.headerlink {
+  visibility: hidden;
+  color: #dddddd;
+  padding-left: .3em;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+  visibility: visible;
+}
+
+
+
+/* Header */
+
+div.header {
+  padding-top: 10px;
+  padding-bottom: 10px;
+}
+
+div.header h1 {
+  font-family: {{ theme_headerfont }};
+  font-weight: normal;
+  font-size: 160%;
+  letter-spacing: .08em;
+}
+
+div.header h1 a {
+  color: white;
+}
+
+div.header div.rel {
+  margin-top: 1em;
+}
+
+div.header div.rel a {
+  color: {{ theme_headerlinkcolor }};
+  letter-spacing: .1em;
+  text-transform: uppercase;
+}
+
+p.logo {
+    float: right;
+}
+
+img.logo {
+    border: 0;
+}
+
+
+/* Content */
+div.content-wrapper {
+  background-color: white;
+  padding-top: 20px;
+  padding-bottom: 20px;
+}
+
+div.document {
+  width: {{ theme_documentwidth }};
+  float: left;
+}
+
+div.body {
+  padding-right: 2em;
+  text-align: justify;
+}
+
+div.document ul {
+  margin-left: 1.2em;
+  list-style-type: square;
+}
+
+div.document dd {
+  margin-left: 1.2em;
+  margin-top: .4em;
+  margin-bottom: 1em;
+}
+
+div.document .section {
+  margin-top: 1.7em;
+}
+div.document .section:first-child {
+  margin-top: 0px;
+}
+
+div.document div.highlight {
+  padding: 3px;
+  background-color: #eeeeec;
+  border-top: 2px solid #dddddd;
+  border-bottom: 2px solid #dddddd;
+  margin-top: .8em;
+  margin-bottom: .8em;
+}
+
+div.document h2 {
+  margin-top: .7em;
+}
+
+div.document p {
+  margin-bottom: .5em;
+}
+
+div.document li.toctree-l1 {
+  margin-bottom: 1em;
+}
+
+div.document .descname {
+  font-weight: bold;
+}
+
+div.document .docutils.literal {
+  background-color: #eeeeec;
+  padding: 1px;
+}
+
+div.document .docutils.xref.literal {
+  background-color: transparent;
+  padding: 0px;
+}
+
+
+/* Sidebar */
+
+div.sidebar {
+  width: {{ theme_sidebarwidth }};
+  float: right;
+  font-size: .9em;
+}
+
+div.sidebar h3 {
+  color: #2e3436;
+  text-transform: uppercase;
+  font-size: 130%;
+  letter-spacing: .1em;
+}
+
+div.sidebar ul {
+  list-style-type: none;
+}
+
+div.sidebar li.toctree-l1 a {
+  display: block;
+  padding: 1px;
+  border: 1px solid #dddddd;
+  background-color: #eeeeec;
+  margin-bottom: .4em;
+  padding-left: 3px;
+  color: #2e3436;
+}
+
+div.sidebar li.toctree-l2 a {
+  background-color: transparent;
+  border: none;
+  border-bottom: 1px solid #dddddd;
+}
+
+div.sidebar li.toctree-l2:last-child a {
+  border-bottom: none;
+}
+
+div.sidebar li.toctree-l1.current a {
+  border-right: 5px solid {{ theme_headerlinkcolor }};
+}
+
+div.sidebar li.toctree-l1.current li.toctree-l2 a {
+  border-right: none;
+}
+
+
+/* Footer */
+
+div.footer-wrapper {
+  background: {{ theme_footerbg }};
+  border-top: 4px solid #babdb6;
+  padding-top: 10px;
+  padding-bottom: 10px;
+  min-height: 80px;
+}
+
+div.footer, div.footer a {
+  color: #888a85;
+}
+
+div.footer .right {
+  text-align: right;
+}
+
+div.footer .left {
+  text-transform: uppercase;
+}
+
+
+/* Styles copied form basic theme */
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+    margin: 10px 0 0 20px;
+    padding: 0;
+}
+
+ul.search li {
+    padding: 5px 0 5px 20px;
+    background-image: url(file.png);
+    background-repeat: no-repeat;
+    background-position: 0 7px;
+}
+
+ul.search li a {
+    font-weight: bold;
+}
+
+ul.search li div.context {
+    color: #888;
+    margin: 2px 0 0 30px;
+    text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+    font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+    width: 90%;
+}
+
+table.contentstable p.biglink {
+    line-height: 150%;
+}
+
+a.biglink {
+    font-size: 1.3em;
+}
+
+span.linkdescr {
+    font-style: italic;
+    padding-top: 5px;
+    font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable td {
+    text-align: left;
+    vertical-align: top;
+}
+
+table.indextable dl, table.indextable dd {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+table.indextable tr.pcap {
+    height: 10px;
+}
+
+table.indextable tr.cap {
+    margin-top: 10px;
+    background-color: #f2f2f2;
+}
+
+img.toggler {
+    margin-right: 3px;
+    margin-top: 3px;
+    cursor: pointer;
+}
+

sphinx/themes/agogo/theme.conf

@@ -0,0 +1,18 @@
+[theme]
+inherit = basic
+stylesheet = agogo.css
+pygments_style = tango
+
+[options]
+bodyfont = "Verdana", Arial, sans-serif
+headerfont = "Georgia", "Times New Roman", serif
+pagewidth = 70em
+documentwidth = 50em
+sidebarwidth = 20em
+bgcolor = #eeeeec
+headerbg = url(bgtop.png) top left repeat-x
+footerbg = url(bgfooter.png) top left repeat-x
+linkcolor = #ce5c00
+headercolor1 = #204a87
+headercolor2 = #3465a4
+headerlinkcolor = #fcaf3e

sphinx/themes/basic/layout.html

@@ -159,6 +159,7 @@
 
 {%- block relbar1 %}{{ relbar() }}{% endblock %}
 
+{%- block content %}
   {%- block sidebar1 %} {# possible location for sidebar #} {% endblock %}
 
     <div class="document">
@@ -179,6 +180,7 @@
   {%- block sidebar2 %}{{ sidebar() }}{% endblock %}
       <div class="clearer"></div>
     </div>
+{%- endblock %}
 
 {%- block relbar2 %}{{ relbar() }}{% endblock %}
 

tests/test_theming.py

@@ -24,8 +24,8 @@ def test_theme_api(app):
 
     # test Theme class API
     assert set(Theme.themes.keys()) == \
-           set(['basic', 'default', 'scrolls', 'sphinxdoc', 'traditional',
-                'testtheme', 'ziptheme'])
+           set(['basic', 'default', 'scrolls', 'agogo', 'sphinxdoc',
+                'traditional', 'testtheme', 'ziptheme'])
     assert Theme.themes['testtheme'][1] is None
     assert isinstance(Theme.themes['ziptheme'][1], zipfile.ZipFile)