2009-02-15 09:10:10 -06:00
|
|
|
"""Test the Theme class."""
|
|
|
|
|
|
|
|
|
|
import os
|
2024-03-22 06:57:34 -05:00
|
|
|
import shutil
|
|
|
|
|
from xml.etree.ElementTree import ParseError
|
2009-02-15 09:10:10 -06:00
|
|
|
|
2020-03-14 13:46:37 -05:00
|
|
|
import pytest
|
2024-03-22 06:57:34 -05:00
|
|
|
from defusedxml.ElementTree import parse as xml_parse
|
2020-11-11 05:00:27 -06:00
|
|
|
|
2023-08-07 15:02:25 -05:00
|
|
|
import sphinx.builders.html
|
2024-01-17 19:54:32 -06:00
|
|
|
from sphinx.errors import ThemeError
|
2024-04-09 18:10:26 -05:00
|
|
|
from sphinx.theming import _load_theme
|
2015-03-14 10:47:43 -05:00
|
|
|
|
|
|
|
|
|
2017-01-05 10:14:47 -06:00
|
|
|
@pytest.mark.sphinx(
|
2017-12-13 08:48:07 -06:00
|
|
|
testroot='theming',
|
2024-03-22 06:57:34 -05:00
|
|
|
confoverrides={'html_theme': 'ziptheme', 'html_theme_options.testopt': 'foo'},
|
|
|
|
|
)
|
2014-09-21 10:17:02 -05:00
|
|
|
def test_theme_api(app, status, warning):
|
2024-03-22 06:57:34 -05:00
|
|
|
themes = [
|
|
|
|
|
'basic',
|
|
|
|
|
'default',
|
|
|
|
|
'scrolls',
|
|
|
|
|
'agogo',
|
|
|
|
|
'sphinxdoc',
|
|
|
|
|
'haiku',
|
|
|
|
|
'traditional',
|
|
|
|
|
'epub',
|
|
|
|
|
'nature',
|
|
|
|
|
'pyramid',
|
|
|
|
|
'bizstyle',
|
|
|
|
|
'classic',
|
|
|
|
|
'nonav',
|
|
|
|
|
'test-theme',
|
|
|
|
|
'ziptheme',
|
|
|
|
|
'staticfiles',
|
|
|
|
|
'parent',
|
|
|
|
|
'child',
|
|
|
|
|
'alabaster',
|
|
|
|
|
]
|
2018-06-19 07:58:06 -05:00
|
|
|
|
2009-02-15 09:10:10 -06:00
|
|
|
# test Theme class API
|
2021-12-10 19:52:22 -06:00
|
|
|
assert set(app.registry.html_themes.keys()) == set(themes)
|
2024-03-22 06:57:34 -05:00
|
|
|
assert app.registry.html_themes['test-theme'] == str(
|
|
|
|
|
app.srcdir / 'test_theme' / 'test-theme'
|
|
|
|
|
)
|
2023-07-27 18:39:12 -05:00
|
|
|
assert app.registry.html_themes['ziptheme'] == str(app.srcdir / 'ziptheme.zip')
|
2024-03-22 06:57:34 -05:00
|
|
|
assert app.registry.html_themes['staticfiles'] == str(
|
|
|
|
|
app.srcdir / 'test_theme' / 'staticfiles'
|
|
|
|
|
)
|
2009-02-15 09:10:10 -06:00
|
|
|
|
|
|
|
|
# test Theme instance API
|
|
|
|
|
theme = app.builder.theme
|
|
|
|
|
assert theme.name == 'ziptheme'
|
2017-04-20 09:38:48 -05:00
|
|
|
assert len(theme.get_theme_dirs()) == 2
|
2009-02-15 09:10:10 -06:00
|
|
|
|
|
|
|
|
# direct setting
|
2017-04-20 09:38:48 -05:00
|
|
|
assert theme.get_config('theme', 'stylesheet') == 'custom.css'
|
2009-02-15 09:10:10 -06:00
|
|
|
# inherited setting
|
2017-04-20 09:38:48 -05:00
|
|
|
assert theme.get_config('options', 'nosidebar') == 'false'
|
2009-02-15 09:10:10 -06:00
|
|
|
# nonexisting setting
|
2017-04-20 09:38:48 -05:00
|
|
|
assert theme.get_config('theme', 'foobar', 'def') == 'def'
|
2017-01-05 09:46:42 -06:00
|
|
|
with pytest.raises(ThemeError):
|
2017-04-20 09:38:48 -05:00
|
|
|
theme.get_config('theme', 'foobar')
|
2009-02-15 09:10:10 -06:00
|
|
|
|
|
|
|
|
# options API
|
2017-06-26 02:17:08 -05:00
|
|
|
|
|
|
|
|
options = theme.get_options({'nonexisting': 'foo'})
|
2023-08-13 17:06:27 -05:00
|
|
|
assert 'nonexisting' not in options
|
2017-06-26 02:17:08 -05:00
|
|
|
|
2024-01-08 18:19:28 -06:00
|
|
|
options = theme.get_options(app.config.html_theme_options)
|
2009-02-15 09:10:10 -06:00
|
|
|
assert options['testopt'] == 'foo'
|
|
|
|
|
assert options['nosidebar'] == 'false'
|
|
|
|
|
|
|
|
|
|
# cleanup temp directories
|
2024-01-08 18:19:28 -06:00
|
|
|
theme._cleanup()
|
2024-01-17 19:55:52 -06:00
|
|
|
assert not any(map(os.path.exists, theme._tmp_dirs))
|
2014-06-07 04:32:56 -05:00
|
|
|
|
2014-09-21 10:17:02 -05:00
|
|
|
|
2023-09-14 05:49:41 -05:00
|
|
|
def test_nonexistent_theme_conf(tmp_path):
|
|
|
|
|
# Check that error occurs with a non-existent theme.conf
|
|
|
|
|
# (https://github.com/sphinx-doc/sphinx/issues/11668)
|
|
|
|
|
with pytest.raises(ThemeError):
|
2024-04-09 18:10:26 -05:00
|
|
|
_load_theme('', str(tmp_path))
|
2023-09-14 05:49:41 -05:00
|
|
|
|
|
|
|
|
|
2017-01-05 10:14:47 -06:00
|
|
|
@pytest.mark.sphinx(testroot='double-inheriting-theme')
|
2017-04-20 00:04:49 -05:00
|
|
|
def test_double_inheriting_theme(app, status, warning):
|
|
|
|
|
assert app.builder.theme.name == 'base_theme2'
|
|
|
|
|
app.build() # => not raises TemplateNotFound
|
2017-04-18 09:22:03 -05:00
|
|
|
|
|
|
|
|
|
2024-03-22 06:57:34 -05:00
|
|
|
@pytest.mark.sphinx(testroot='theming', confoverrides={'html_theme': 'child'})
|
2017-04-18 09:22:03 -05:00
|
|
|
def test_nested_zipped_theme(app, status, warning):
|
2017-04-20 00:04:49 -05:00
|
|
|
assert app.builder.theme.name == 'child'
|
2017-04-18 09:22:03 -05:00
|
|
|
app.build() # => not raises TemplateNotFound
|
2017-10-22 01:12:31 -05:00
|
|
|
|
|
|
|
|
|
2024-03-22 06:57:34 -05:00
|
|
|
@pytest.mark.sphinx(testroot='theming', confoverrides={'html_theme': 'staticfiles'})
|
2017-12-13 08:48:07 -06:00
|
|
|
def test_staticfiles(app, status, warning):
|
|
|
|
|
app.build()
|
|
|
|
|
assert (app.outdir / '_static' / 'staticimg.png').exists()
|
|
|
|
|
assert (app.outdir / '_static' / 'statictmpl.html').exists()
|
2022-04-26 21:04:19 -05:00
|
|
|
assert (app.outdir / '_static' / 'statictmpl.html').read_text(encoding='utf8') == (
|
2024-03-22 06:57:34 -05:00
|
|
|
'<!-- testing static templates -->\n<html><project>Python</project></html>'
|
2017-12-13 08:48:07 -06:00
|
|
|
)
|
|
|
|
|
|
2022-04-26 21:04:19 -05:00
|
|
|
result = (app.outdir / 'index.html').read_text(encoding='utf8')
|
2017-12-13 08:48:07 -06:00
|
|
|
assert '<meta name="testopt" content="optdefault" />' in result
|
2017-12-15 09:53:55 -06:00
|
|
|
|
|
|
|
|
|
2024-03-22 06:57:34 -05:00
|
|
|
@pytest.mark.sphinx(testroot='theming', confoverrides={'html_theme': 'test-theme'})
|
2023-08-07 15:02:25 -05:00
|
|
|
def test_dark_style(app, monkeypatch):
|
|
|
|
|
monkeypatch.setattr(sphinx.builders.html, '_file_checksum', lambda o, f: '')
|
|
|
|
|
|
2020-03-14 12:49:25 -05:00
|
|
|
style = app.builder.dark_highlighter.formatter_args.get('style')
|
2020-03-14 12:46:02 -05:00
|
|
|
assert style.__name__ == 'MonokaiStyle'
|
|
|
|
|
|
|
|
|
|
app.build()
|
|
|
|
|
assert (app.outdir / '_static' / 'pygments_dark.css').exists()
|
|
|
|
|
|
2023-08-07 15:02:25 -05:00
|
|
|
css_file, properties = app.registry.css_files[0]
|
|
|
|
|
assert css_file == 'pygments_dark.css'
|
2024-03-22 06:57:34 -05:00
|
|
|
assert 'media' in properties
|
|
|
|
|
assert properties['media'] == '(prefers-color-scheme: dark)'
|
2023-08-07 15:02:25 -05:00
|
|
|
|
2023-08-11 19:46:44 -05:00
|
|
|
assert sorted(f.filename for f in app.builder._css_files) == [
|
2023-08-07 15:02:25 -05:00
|
|
|
'_static/classic.css',
|
|
|
|
|
'_static/pygments.css',
|
|
|
|
|
'_static/pygments_dark.css',
|
|
|
|
|
]
|
|
|
|
|
|
2022-04-26 21:04:19 -05:00
|
|
|
result = (app.outdir / 'index.html').read_text(encoding='utf8')
|
2023-08-07 15:02:25 -05:00
|
|
|
assert '<link rel="stylesheet" type="text/css" href="_static/pygments.css" />' in result
|
2024-03-22 06:57:34 -05:00
|
|
|
assert (
|
|
|
|
|
'<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" '
|
|
|
|
|
'rel="stylesheet" type="text/css" '
|
|
|
|
|
'href="_static/pygments_dark.css" />'
|
|
|
|
|
) in result
|
2020-03-14 12:46:02 -05:00
|
|
|
|
|
|
|
|
|
2017-10-22 01:12:31 -05:00
|
|
|
@pytest.mark.sphinx(testroot='theming')
|
|
|
|
|
def test_theme_sidebars(app, status, warning):
|
|
|
|
|
app.build()
|
|
|
|
|
|
|
|
|
|
# test-theme specifies globaltoc and searchbox as default sidebars
|
2022-04-26 21:04:19 -05:00
|
|
|
result = (app.outdir / 'index.html').read_text(encoding='utf8')
|
2018-07-21 16:13:16 -05:00
|
|
|
assert '<h3><a href="#">Table of Contents</a></h3>' in result
|
2017-10-22 01:12:31 -05:00
|
|
|
assert '<h3>Related Topics</h3>' not in result
|
|
|
|
|
assert '<h3>This Page</h3>' not in result
|
2019-04-22 05:55:32 -05:00
|
|
|
assert '<h3 id="searchlabel">Quick search</h3>' in result
|
2024-03-22 06:57:34 -05:00
|
|
|
|
|
|
|
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
|
|
|
'theme_name',
|
|
|
|
|
[
|
|
|
|
|
'alabaster',
|
|
|
|
|
'agogo',
|
|
|
|
|
'basic',
|
|
|
|
|
'bizstyle',
|
|
|
|
|
'classic',
|
|
|
|
|
'default',
|
|
|
|
|
'epub',
|
|
|
|
|
'haiku',
|
|
|
|
|
'nature',
|
|
|
|
|
'nonav',
|
|
|
|
|
'pyramid',
|
|
|
|
|
'scrolls',
|
|
|
|
|
'sphinxdoc',
|
|
|
|
|
'traditional',
|
|
|
|
|
],
|
|
|
|
|
)
|
|
|
|
|
def test_theme_builds(make_app, rootdir, sphinx_test_tempdir, theme_name):
|
|
|
|
|
"""Test all the themes included with Sphinx build a simple project and produce valid XML."""
|
|
|
|
|
testroot_path = rootdir / 'test-basic'
|
|
|
|
|
srcdir = sphinx_test_tempdir / f'test-theme-{theme_name}'
|
|
|
|
|
shutil.copytree(testroot_path, srcdir)
|
|
|
|
|
|
|
|
|
|
app = make_app(srcdir=srcdir, confoverrides={'html_theme': theme_name})
|
|
|
|
|
app.build()
|
|
|
|
|
assert not app.warning.getvalue().strip()
|
|
|
|
|
assert app.outdir.joinpath('index.html').exists()
|
|
|
|
|
|
|
|
|
|
# check that the generated HTML files are well-formed (as strict XML)
|
|
|
|
|
for html_file in app.outdir.rglob('*.html'):
|
|
|
|
|
try:
|
|
|
|
|
xml_parse(html_file)
|
|
|
|
|
except ParseError as exc:
|
|
|
|
|
pytest.fail(f'Failed to parse {html_file.relative_to(app.outdir)}: {exc}')
|
