From b78f3090a05f38fb3beb14f7e716f1b26a2ff253 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 22 Oct 2017 15:12:31 +0900 Subject: [PATCH 1/3] HTML themes can set up default sidebars through ``theme.conf`` --- CHANGES | 1 + doc/config.rst | 5 +++-- doc/theming.rst | 7 +++++++ sphinx/builders/html.py | 10 +++++++++- sphinx/templates/quickstart/conf.py_t | 9 +-------- sphinx/themes/basic/theme.conf | 1 + tests/roots/test-basic/index.rst | 3 +++ .../test_theme/test-theme/theme.conf | 1 + tests/test_build_html.py | 18 ++++++++++++++++++ tests/test_theming.py | 12 ++++++++++++ 10 files changed, 56 insertions(+), 11 deletions(-) diff --git a/CHANGES b/CHANGES index a958d185d..e8867b45c 100644 --- a/CHANGES +++ b/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 diff --git a/doc/config.rst b/doc/config.rst index f23c22e00..b2cac41f0 100644 --- a/doc/config.rst +++ b/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 diff --git a/doc/theming.rst b/doc/theming.rst index 01f72fde9..34bca9607 100644 --- a/doc/theming.rst +++ b/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_``. +.. versionadded:: 1.7 + sidebar settings .. _distribute-your-theme: diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 6313eef61..bb19a2d83 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -864,9 +864,16 @@ 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(',')] + + # user sidebar settings for pattern, patsidebars in iteritems(self.config.html_sidebars): if patmatch(pagename, pattern): if matched: @@ -881,6 +888,7 @@ class StandaloneHTMLBuilder(Builder): continue matched = pattern sidebars = patsidebars + if sidebars is None: # keep defaults pass diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t index 8300e626f..9b321a404 100644 --- a/sphinx/templates/quickstart/conf.py_t +++ b/sphinx/templates/quickstart/conf.py_t @@ -110,14 +110,7 @@ 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', - ] -} +# html_sidebars = {} # -- Options for HTMLHelp output ------------------------------------------ diff --git a/sphinx/themes/basic/theme.conf b/sphinx/themes/basic/theme.conf index 3248070bc..25495e8c6 100644 --- a/sphinx/themes/basic/theme.conf +++ b/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 diff --git a/tests/roots/test-basic/index.rst b/tests/roots/test-basic/index.rst index 8c4ca7d80..48407e643 100644 --- a/tests/roots/test-basic/index.rst +++ b/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 diff --git a/tests/roots/test-theming/test_theme/test-theme/theme.conf b/tests/roots/test-theming/test_theme/test-theme/theme.conf index 0d8403f0b..b7518bc9c 100644 --- a/tests/roots/test-theming/test_theme/test-theme/theme.conf +++ b/tests/roots/test-theming/test_theme/test-theme/theme.conf @@ -1,2 +1,3 @@ [theme] inherit = classic +sidebars = globaltoc.html, searchbox.html diff --git a/tests/test_build_html.py b/tests/test_build_html.py index ceeb5f01c..5eaccb2bb 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -1245,3 +1245,21 @@ def test_html_remote_images(app, status, warning): assert ('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 '

Table Of Contents

' in result + assert '

Related Topics

' in result + assert '

This Page

' in result + assert '

Quick search

' in result + + app.config.html_sidebars = {'**': []} + app.builder.build_all() + result = (app.outdir / 'index.html').text(encoding='utf8') + assert '

Table Of Contents

' not in result + assert '

Related Topics

' not in result + assert '

This Page

' not in result + assert '

Quick search

' not in result diff --git a/tests/test_theming.py b/tests/test_theming.py index 408a6503f..4a6b8c956 100644 --- a/tests/test_theming.py +++ b/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 '

Table Of Contents

' in result + assert '

Related Topics

' not in result + assert '

This Page

' not in result + assert '

Quick search

' in result From 6288eac1ece9b1d684d8611c32afb027d56b0033 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 26 Oct 2017 00:01:09 +0900 Subject: [PATCH 2/3] Provide default settings for alabaster --- sphinx/builders/html.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index bb19a2d83..5c35fa145 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -872,6 +872,11 @@ class StandaloneHTMLBuilder(Builder): 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): From c0aa0ce2d8bd96406f785dd5d225eca68b32b69b Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 26 Oct 2017 00:04:23 +0900 Subject: [PATCH 3/3] Add hints for html_sidebars --- sphinx/templates/quickstart/conf.py_t | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t index 9b321a404..4e828f330 100644 --- a/sphinx/templates/quickstart/conf.py_t +++ b/sphinx/templates/quickstart/conf.py_t @@ -110,6 +110,11 @@ html_static_path = ['{{ dot }}static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # +# 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 = {}