Merge pull request #4177 from tk0miya/improve_theme_sidebars

HTML themes can set up default sidebars through ``theme.conf``

CHANGES

@@ -38,6 +38,7 @@ Features added
 * #1448: qthelp: Add new config value; :confval:`qthelp_namespace`
 * #4140: html themes: Make body tag inheritable
 * #4168: improve zh search with jieba
+* HTML themes can set up default sidebars through ``theme.conf``
 
 
 Features removed

doc/config.rst

@@ -820,8 +820,9 @@ that use Sphinx's HTMLWriter class.
      to include.  If all or some of the default sidebars are to be included,
      they must be put into this list as well.
 
-     The default sidebars (for documents that don't match any pattern) are:
-     ``['localtoc.html', 'relations.html', 'sourcelink.html',
+     The default sidebars (for documents that don't match any pattern) are
+     defined by theme itself.  Builtin themes are using these templates by
+     default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
      'searchbox.html']``.
 
    * If a value is a single string, it specifies a custom sidebar to be added

doc/theming.rst

@@ -276,6 +276,7 @@ Python :mod:`ConfigParser` module) and has the following structure:
     inherit = base theme
     stylesheet = main CSS name
     pygments_style = stylename
+    sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
 
     [options]
     variable = default value
@@ -295,10 +296,16 @@ Python :mod:`ConfigParser` module) and has the following structure:
   highlighting.  This can be overridden by the user in the
   :confval:`pygments_style` config value.
 
+* The **sidebars** setting gives the comma separated list of sidebar templates
+  for constructing sidebars.  This can be overridden by the user in the
+  :confval:`html_sidebars` config value.
+
 * The **options** section contains pairs of variable names and default values.
   These options can be overridden by the user in :confval:`html_theme_options`
   and are accessible from all templates as ``theme_<name>``.
 
+.. versionadded:: 1.7
+   sidebar settings
 
 .. _distribute-your-theme:
 

sphinx/builders/html.py

@@ -864,9 +864,21 @@ class StandaloneHTMLBuilder(Builder):
         def has_wildcard(pattern):
             # type: (unicode) -> bool
             return any(char in pattern for char in '*?[')
-        sidebars = None
+        sidebars = self.theme.get_config('theme', 'sidebars', None)
         matched = None
         customsidebar = None
+
+        # default sidebars settings for selected theme
+        theme_default_sidebars = self.theme.get_config('theme', 'sidebars', None)
+        if theme_default_sidebars:
+            sidebars = [name.strip() for name in theme_default_sidebars.split(',')]
+        elif self.theme.name == 'alabaster':
+            # provide default settings for alabaster (for compatibility)
+            # Note: this will be removed before Sphinx-2.0
+            sidebars = ['about.html', 'navigation.html', 'relation.html',
+                        'searchbox.html', 'donate.html']
+
+        # user sidebar settings
         for pattern, patsidebars in iteritems(self.config.html_sidebars):
             if patmatch(pagename, pattern):
                 if matched:
@@ -881,6 +893,7 @@ class StandaloneHTMLBuilder(Builder):
                         continue
                 matched = pattern
                 sidebars = patsidebars
+
         if sidebars is None:
             # keep defaults
             pass

sphinx/templates/quickstart/conf.py_t

@@ -110,14 +110,12 @@ html_static_path = ['{{ dot }}static']
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-    ]
-}
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
 
 
 # -- Options for HTMLHelp output ------------------------------------------

sphinx/themes/basic/theme.conf

@@ -2,6 +2,7 @@
 inherit = none
 stylesheet = basic.css
 pygments_style = none
+sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
 
 [options]
 nosidebar = false

tests/roots/test-basic/index.rst

@@ -12,6 +12,9 @@ Sphinx uses reStructuredText as its markup language, and many of its strengths
 come from the power and straightforwardness of reStructuredText and its parsing
 and translating suite, the Docutils.
 
+features
+--------
+
 Among its features are the following:
 
 * Output formats: HTML (including derivative formats such as HTML Help, Epub

tests/roots/test-theming/test_theme/test-theme/theme.conf

@@ -1,2 +1,3 @@
 [theme]
 inherit = classic
+sidebars = globaltoc.html, searchbox.html

tests/test_build_html.py

@@ -1245,3 +1245,21 @@ def test_html_remote_images(app, status, warning):
     assert ('<img alt="https://www.python.org/static/img/python-logo.png" '
             'src="https://www.python.org/static/img/python-logo.png" />' in result)
     assert not (app.outdir / 'python-logo.png').exists()
+
+
+@pytest.mark.sphinx('html', testroot='basic')
+def test_html_sidebar(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'index.html').text(encoding='utf8')
+    assert '<h3><a href="#">Table Of Contents</a></h3>' in result
+    assert '<h3>Related Topics</h3>' in result
+    assert '<h3>This Page</h3>' in result
+    assert '<h3>Quick search</h3>' in result
+
+    app.config.html_sidebars = {'**': []}
+    app.builder.build_all()
+    result = (app.outdir / 'index.html').text(encoding='utf8')
+    assert '<h3><a href="#">Table Of Contents</a></h3>' not in result
+    assert '<h3>Related Topics</h3>' not in result
+    assert '<h3>This Page</h3>' not in result
+    assert '<h3>Quick search</h3>' not in result

tests/test_theming.py

@@ -95,3 +95,15 @@ def test_double_inheriting_theme(app, status, warning):
 def test_nested_zipped_theme(app, status, warning):
     assert app.builder.theme.name == 'child'
     app.build()  # => not raises TemplateNotFound
+
+
+@pytest.mark.sphinx(testroot='theming')
+def test_theme_sidebars(app, status, warning):
+    app.build()
+
+    # test-theme specifies globaltoc and searchbox as default sidebars
+    result = (app.outdir / 'index.html').text(encoding='utf8')
+    assert '<h3><a href="#">Table Of Contents</a></h3>' in result
+    assert '<h3>Related Topics</h3>' not in result
+    assert '<h3>This Page</h3>' not in result
+    assert '<h3>Quick search</h3>' in result