merge with trunk (and remove debugging leftover from test layout.html template)

doc/templating.rst

@@ -139,23 +139,36 @@ The following blocks exist in the ``layout.html`` template:
     The logo location within the sidebar.  Override this if you want to place
     some content at the top of the sidebar.
 
+`footer`
+    The block for the footer div.  If you want a custom footer or markup before
+    or after it, override this one.
+
+The following four blocks are *only* used for pages that do not have assigned a
+list of custom sidebars in the :confval:`html_sidebars` config value.  Their use
+is deprecated in favor of separate sidebar templates, which can be included via
+:confval:`html_sidebars`.
+
 `sidebartoc`
     The table of contents within the sidebar.
 
+    .. deprecated:: 1.0
+
 `sidebarrel`
     The relation links (previous, next document) within the sidebar.
 
+    .. deprecated:: 1.0
+
 `sidebarsourcelink`
     The "Show source" link within the sidebar (normally only shown if this is
     enabled by :confval:`html_show_sourcelink`).
 
+    .. deprecated:: 1.0
+
 `sidebarsearch`
     The search box within the sidebar.  Override this if you want to place some
     content at the bottom of the sidebar.
 
-`footer`
+    .. deprecated:: 1.0
-    The block for the footer div.  If you want a custom footer or markup before
-    or after it, override this one.
 
 
 Configuration Variables

sphinx/builders/html.py

@@ -670,11 +670,12 @@ class StandaloneHTMLBuilder(Builder):
     def get_outfilename(self, pagename):
         return path.join(self.outdir, os_path(pagename) + self.out_suffix)
 
-    def get_sidebars(self, pagename):
+    def add_sidebars(self, pagename, ctx):
         def has_wildcard(pattern):
             return any(char in pattern for char in '*?[')
         sidebars = None
         matched = None
+        customsidebar = None
         for pattern, patsidebars in self.config.html_sidebars.iteritems():
             if patmatch(pagename, pattern):
                 if matched:
@@ -690,12 +691,14 @@ class StandaloneHTMLBuilder(Builder):
                 matched = pattern
                 sidebars = patsidebars
         if sidebars is None:
-            sidebars = self.default_sidebars
+            # keep defaults
+            pass
         elif isinstance(sidebars, basestring):
             # 0.x compatible mode: insert custom sidebar before searchbox
-            sidebars = self.default_sidebars[:-1] + [sidebars] + \
+            customsidebar = sidebars
-                       self.default_sidebars[-1:]
+            sidebars = None
-        return sidebars
+        ctx['sidebars'] = sidebars
+        ctx['customsidebar'] = customsidebar
 
     # --------- these are overwritten by the serialization builder
 
@@ -718,7 +721,7 @@ class StandaloneHTMLBuilder(Builder):
         ctx['hasdoc'] = lambda name: name in self.env.all_docs
         ctx['encoding'] = encoding = self.config.html_output_encoding
         ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw)
-        ctx['sidebars'] = self.get_sidebars(pagename)
+        self.add_sidebars(pagename, ctx)
         ctx.update(addctx)
 
         self.app.emit('html-page-context', pagename, templatename,
@@ -842,7 +845,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder):
     def handle_page(self, pagename, ctx, templatename='page.html',
                     outfilename=None, event_arg=None):
         ctx['current_page_name'] = pagename
-        ctx['sidebars'] = self.get_sidebars(pagename)
+        self.add_sidebars(pagename, ctx)
 
         if not outfilename:
             outfilename = path.join(self.outdir,

sphinx/themes/basic/globaltoc.html

@@ -7,9 +7,7 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
-{%- block sidebartoc %}
 {%- if display_toc %}
   <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
   {{ toctree() }}
 {%- endif %}
-{%- endblock %}

sphinx/themes/basic/layout.html

@@ -46,9 +46,29 @@
             </a></p>
           {%- endif %}
           {%- endblock %}
-          {%- for sidebar in sidebars %}
+          {%- if sidebars %}
-          {%- include sidebar %}
+            {#- new style sidebar: explicitly include/exclude templates #}
-          {%- endfor %}
+            {%- for sidebar in sidebars %}
+            {%- include sidebar %}
+            {%- endfor %}
+          {%- else %}
+            {#- old style sidebars: using blocks -- should be deprecated #}
+            {%- block sidebartoc %}
+            {%- include "localtoc.html" %}
+            {%- endblock %}
+            {%- block sidebarrel %}
+            {%- include "relations.html" %}
+            {%- endblock %}
+            {%- block sidebarsourcelink %}
+            {%- include "sourcelink.html" %}
+            {%- endblock %}
+            {%- if customsidebar %}
+            {%- include customsidebar %}
+            {%- endif %}
+            {%- block sidebarsearch %}
+            {%- include "searchbox.html" %}
+            {%- endblock %}
+          {%- endif %}
         </div>
       </div>
       {%- endif %}{% endif %}

sphinx/themes/basic/localtoc.html

@@ -7,9 +7,7 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
-{%- block sidebartoc %}
 {%- if display_toc %}
   <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
   {{ toc }}
 {%- endif %}
-{%- endblock %}

sphinx/themes/basic/relations.html

@@ -7,7 +7,6 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
-{%- block sidebarrel %}
 {%- if prev %}
   <h4>{{ _('Previous topic') }}</h4>
   <p class="topless"><a href="{{ prev.link|e }}"
@@ -18,4 +17,3 @@
   <p class="topless"><a href="{{ next.link|e }}"
                         title="{{ _('next chapter') }}">{{ next.title }}</a></p>
 {%- endif %}
-{%- endblock %}

sphinx/themes/basic/searchbox.html

@@ -7,7 +7,6 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
-{%- block sidebarsearch %}
 {%- if pagename != "search" %}
 <div id="searchbox" style="display: none">
   <h3>{{ _('Quick search') }}</h3>
@@ -23,4 +22,3 @@
 </div>
 <script type="text/javascript">$('#searchbox').show(0);</script>
 {%- endif %}
-{%- endblock %}

sphinx/themes/basic/sourcelink.html

@@ -7,7 +7,6 @@
     :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
-{%- block sidebarsourcelink %}
 {%- if show_source and has_source and sourcename %}
   <h3>{{ _('This Page') }}</h3>
   <ul class="this-page-menu">
@@ -15,4 +14,3 @@
            rel="nofollow">{{ _('Show Source') }}</a></li>
   </ul>
 {%- endif %}
-{%- endblock %}

tests/root/_templates/layout.html

@@ -11,6 +11,5 @@
 {% block sidebartoc %}
 {# display global TOC in addition to local TOC #}
 {{ super() }}
-{{ 1/0 }}
 {{ toctree(collapse=False, maxdepth=-1) }}
 {% endblock %}