Commits

Georg Brandl  committed 5dcd90e

Fix compatibility with blocks in the old sidebar scheme: blocks cannot be used in included templates. Deprecate the blocks accordingly.

  • Participants
  • Parent commits 28d4a54

Comments (0)

Files changed (8)

File doc/templating.rst

     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`
-    The block for the footer div.  If you want a custom footer or markup before
-    or after it, override this one.
+    .. deprecated:: 1.0
 
 
 Configuration Variables

File sphinx/builders/html.py

     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:
                 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] + \
-                       self.default_sidebars[-1:]
-        return sidebars
+            customsidebar = sidebars
+            sidebars = None
+        ctx['sidebars'] = sidebars
+        ctx['customsidebar'] = customsidebar
 
     # --------- these are overwritten by the serialization 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,
     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,

File sphinx/themes/basic/globaltoc.html

     :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 %}

File sphinx/themes/basic/layout.html

             </a></p>
           {%- endif %}
           {%- endblock %}
-          {%- for sidebar in sidebars %}
-          {%- include sidebar %}
-          {%- endfor %}
+          {%- if sidebars %}
+            {#- new style sidebar: explicitly include/exclude templates #}
+            {%- 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 %}

File sphinx/themes/basic/localtoc.html

     :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 %}

File sphinx/themes/basic/relations.html

     :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 }}"
   <p class="topless"><a href="{{ next.link|e }}"
                         title="{{ _('next chapter') }}">{{ next.title }}</a></p>
 {%- endif %}
-{%- endblock %}

File sphinx/themes/basic/searchbox.html

     :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>
 </div>
 <script type="text/javascript">$('#searchbox').show(0);</script>
 {%- endif %}
-{%- endblock %}

File sphinx/themes/basic/sourcelink.html

     :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">
            rel="nofollow">{{ _('Show Source') }}</a></li>
   </ul>
 {%- endif %}
-{%- endblock %}