From 03b9d79b347737f73d05b0d3e47782e3183840c7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 7 Jan 2010 21:49:31 +0100 Subject: [PATCH] Fix compatibility with blocks in the old sidebar scheme: blocks cannot be used in included templates. Deprecate the blocks accordingly. --- doc/templating.rst | 19 ++++++++++++++++--- sphinx/builders/html.py | 17 ++++++++++------- sphinx/themes/basic/globaltoc.html | 2 -- sphinx/themes/basic/layout.html | 26 +++++++++++++++++++++++--- sphinx/themes/basic/localtoc.html | 2 -- sphinx/themes/basic/relations.html | 2 -- sphinx/themes/basic/searchbox.html | 2 -- sphinx/themes/basic/sourcelink.html | 2 -- 8 files changed, 49 insertions(+), 23 deletions(-) diff --git a/doc/templating.rst b/doc/templating.rst index 0148ed32c..abcc478a0 100644 --- a/doc/templating.rst +++ b/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` - 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 diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 7cf5fdf68..cdabcd65c 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -665,11 +665,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: @@ -685,12 +686,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] + \ - self.default_sidebars[-1:] - return sidebars + customsidebar = sidebars + sidebars = None + ctx['sidebars'] = sidebars + ctx['customsidebar'] = customsidebar # --------- these are overwritten by the serialization builder @@ -713,7 +716,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, @@ -828,7 +831,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, diff --git a/sphinx/themes/basic/globaltoc.html b/sphinx/themes/basic/globaltoc.html index 472af34f0..c53324714 100644 --- a/sphinx/themes/basic/globaltoc.html +++ b/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 %}

{{ _('Table Of Contents') }}

{{ toctree() }} {%- endif %} -{%- endblock %} diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index 97b68f8a0..f489a656d 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -46,9 +46,29 @@

{%- 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 %} {%- endif %}{% endif %} diff --git a/sphinx/themes/basic/localtoc.html b/sphinx/themes/basic/localtoc.html index dab70cd88..896eda9ce 100644 --- a/sphinx/themes/basic/localtoc.html +++ b/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 %}

{{ _('Table Of Contents') }}

{{ toc }} {%- endif %} -{%- endblock %} diff --git a/sphinx/themes/basic/relations.html b/sphinx/themes/basic/relations.html index 18e7cc4c3..b693daf88 100644 --- a/sphinx/themes/basic/relations.html +++ b/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 %}

{{ _('Previous topic') }}

{{ next.title }}

{%- endif %} -{%- endblock %} diff --git a/sphinx/themes/basic/searchbox.html b/sphinx/themes/basic/searchbox.html index fb5e08896..56d6617c9 100644 --- a/sphinx/themes/basic/searchbox.html +++ b/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" %} {%- endif %} -{%- endblock %} diff --git a/sphinx/themes/basic/sourcelink.html b/sphinx/themes/basic/sourcelink.html index 665e12728..8fa7563b4 100644 --- a/sphinx/themes/basic/sourcelink.html +++ b/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 %}

{{ _('This Page') }}

{%- endif %} -{%- endblock %}