diff options
Diffstat (limited to '')
-rw-r--r-- | tests/test_theming.py | 131 | ||||
-rw-r--r-- | tests/test_theming/__init__.py | 0 | ||||
-rw-r--r-- | tests/test_theming/test_html_theme.py | 35 | ||||
-rw-r--r-- | tests/test_theming/test_templating.py (renamed from tests/test_templating.py) | 21 | ||||
-rw-r--r-- | tests/test_theming/test_theming.py | 227 | ||||
-rw-r--r-- | tests/test_theming/theme.conf | 7 | ||||
-rw-r--r-- | tests/test_theming/theme.toml | 10 |
7 files changed, 293 insertions, 138 deletions
diff --git a/tests/test_theming.py b/tests/test_theming.py deleted file mode 100644 index b4c8511..0000000 --- a/tests/test_theming.py +++ /dev/null @@ -1,131 +0,0 @@ -"""Test the Theme class.""" - -import os - -import alabaster -import pytest - -import sphinx.builders.html -from sphinx.theming import ThemeError - - -@pytest.mark.sphinx( - testroot='theming', - confoverrides={'html_theme': 'ziptheme', - 'html_theme_options.testopt': 'foo'}) -def test_theme_api(app, status, warning): - cfg = app.config - - themes = ['basic', 'default', 'scrolls', 'agogo', 'sphinxdoc', 'haiku', - 'traditional', 'epub', 'nature', 'pyramid', 'bizstyle', 'classic', 'nonav', - 'test-theme', 'ziptheme', 'staticfiles', 'parent', 'child'] - try: - alabaster_version = alabaster.__version_info__ - except AttributeError: - alabaster_version = alabaster.version.__version_info__ - if alabaster_version >= (0, 7, 11): - themes.append('alabaster') - - # test Theme class API - assert set(app.registry.html_themes.keys()) == set(themes) - assert app.registry.html_themes['test-theme'] == str(app.srcdir / 'test_theme' / 'test-theme') - assert app.registry.html_themes['ziptheme'] == str(app.srcdir / 'ziptheme.zip') - assert app.registry.html_themes['staticfiles'] == str(app.srcdir / 'test_theme' / 'staticfiles') - - # test Theme instance API - theme = app.builder.theme - assert theme.name == 'ziptheme' - themedir = theme.themedir - assert theme.base.name == 'basic' - assert len(theme.get_theme_dirs()) == 2 - - # direct setting - assert theme.get_config('theme', 'stylesheet') == 'custom.css' - # inherited setting - assert theme.get_config('options', 'nosidebar') == 'false' - # nonexisting setting - assert theme.get_config('theme', 'foobar', 'def') == 'def' - with pytest.raises(ThemeError): - theme.get_config('theme', 'foobar') - - # options API - - options = theme.get_options({'nonexisting': 'foo'}) - assert 'nonexisting' not in options - - options = theme.get_options(cfg.html_theme_options) - assert options['testopt'] == 'foo' - assert options['nosidebar'] == 'false' - - # cleanup temp directories - theme.cleanup() - assert not os.path.exists(themedir) - - -@pytest.mark.sphinx(testroot='double-inheriting-theme') -def test_double_inheriting_theme(app, status, warning): - assert app.builder.theme.name == 'base_theme2' - app.build() # => not raises TemplateNotFound - - -@pytest.mark.sphinx(testroot='theming', - confoverrides={'html_theme': 'child'}) -def test_nested_zipped_theme(app, status, warning): - assert app.builder.theme.name == 'child' - app.build() # => not raises TemplateNotFound - - -@pytest.mark.sphinx(testroot='theming', - confoverrides={'html_theme': 'staticfiles'}) -def test_staticfiles(app, status, warning): - app.build() - assert (app.outdir / '_static' / 'staticimg.png').exists() - assert (app.outdir / '_static' / 'statictmpl.html').exists() - assert (app.outdir / '_static' / 'statictmpl.html').read_text(encoding='utf8') == ( - '<!-- testing static templates -->\n' - '<html><project>Python</project></html>' - ) - - result = (app.outdir / 'index.html').read_text(encoding='utf8') - assert '<meta name="testopt" content="optdefault" />' in result - - -@pytest.mark.sphinx(testroot='theming', - confoverrides={'html_theme': 'test-theme'}) -def test_dark_style(app, monkeypatch): - monkeypatch.setattr(sphinx.builders.html, '_file_checksum', lambda o, f: '') - - style = app.builder.dark_highlighter.formatter_args.get('style') - assert style.__name__ == 'MonokaiStyle' - - app.build() - assert (app.outdir / '_static' / 'pygments_dark.css').exists() - - css_file, properties = app.registry.css_files[0] - assert css_file == 'pygments_dark.css' - assert "media" in properties - assert properties["media"] == '(prefers-color-scheme: dark)' - - assert sorted(f.filename for f in app.builder._css_files) == [ - '_static/classic.css', - '_static/pygments.css', - '_static/pygments_dark.css', - ] - - result = (app.outdir / 'index.html').read_text(encoding='utf8') - assert '<link rel="stylesheet" type="text/css" href="_static/pygments.css" />' in result - assert ('<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" ' - 'rel="stylesheet" type="text/css" ' - 'href="_static/pygments_dark.css" />') in result - - -@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').read_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 id="searchlabel">Quick search</h3>' in result diff --git a/tests/test_theming/__init__.py b/tests/test_theming/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tests/test_theming/__init__.py diff --git a/tests/test_theming/test_html_theme.py b/tests/test_theming/test_html_theme.py new file mode 100644 index 0000000..e9a183f --- /dev/null +++ b/tests/test_theming/test_html_theme.py @@ -0,0 +1,35 @@ +import pytest + + +@pytest.mark.sphinx('html', testroot='theming') +def test_theme_options(app, status, warning): + app.build() + + result = (app.outdir / '_static' / 'documentation_options.js').read_text(encoding='utf8') + assert 'NAVIGATION_WITH_KEYS: false' in result + assert 'ENABLE_SEARCH_SHORTCUTS: true' in result + + +@pytest.mark.sphinx( + 'html', + testroot='theming', + confoverrides={ + 'html_theme_options.navigation_with_keys': True, + 'html_theme_options.enable_search_shortcuts': False, + }, +) +def test_theme_options_with_override(app, status, warning): + app.build() + + result = (app.outdir / '_static' / 'documentation_options.js').read_text(encoding='utf8') + assert 'NAVIGATION_WITH_KEYS: true' in result + assert 'ENABLE_SEARCH_SHORTCUTS: false' in result + + +@pytest.mark.sphinx('html', testroot='build-html-theme-having-multiple-stylesheets') +def test_theme_having_multiple_stylesheets(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf-8') + + assert '<link rel="stylesheet" type="text/css" href="_static/mytheme.css" />' in content + assert '<link rel="stylesheet" type="text/css" href="_static/extra.css" />' in content diff --git a/tests/test_templating.py b/tests/test_theming/test_templating.py index a41af93..bc02e97 100644 --- a/tests/test_templating.py +++ b/tests/test_theming/test_templating.py @@ -10,7 +10,7 @@ def test_layout_overloading(make_app, app_params): args, kwargs = app_params app = make_app(*args, **kwargs) setup_documenters(app) - app.builder.build_update() + app.build() result = (app.outdir / 'index.html').read_text(encoding='utf8') assert '<!-- layout overloading -->' in result @@ -21,21 +21,28 @@ def test_autosummary_class_template_overloading(make_app, app_params): args, kwargs = app_params app = make_app(*args, **kwargs) setup_documenters(app) - app.builder.build_update() + app.build() - result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').read_text(encoding='utf8') + result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').read_text( + encoding='utf8' + ) assert 'autosummary/class.rst method block overloading' in result assert 'foobar' not in result -@pytest.mark.sphinx('html', testroot='templating', - confoverrides={'autosummary_context': {'sentence': 'foobar'}}) +@pytest.mark.sphinx( + 'html', + testroot='templating', + confoverrides={'autosummary_context': {'sentence': 'foobar'}}, +) def test_autosummary_context(make_app, app_params): args, kwargs = app_params app = make_app(*args, **kwargs) setup_documenters(app) - app.builder.build_update() + app.build() - result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').read_text(encoding='utf8') + result = (app.outdir / 'generated' / 'sphinx.application.TemplateBridge.html').read_text( + encoding='utf8' + ) assert 'autosummary/class.rst method block overloading' in result assert 'foobar' in result diff --git a/tests/test_theming/test_theming.py b/tests/test_theming/test_theming.py new file mode 100644 index 0000000..867f8a0 --- /dev/null +++ b/tests/test_theming/test_theming.py @@ -0,0 +1,227 @@ +"""Test the Theme class.""" + +import os +import shutil +from pathlib import Path +from xml.etree.ElementTree import ParseError + +import pytest +from defusedxml.ElementTree import parse as xml_parse + +import sphinx.builders.html +from sphinx.errors import ThemeError +from sphinx.theming import ( + _ConfigFile, + _convert_theme_conf, + _convert_theme_toml, + _load_theme, + _load_theme_conf, + _load_theme_toml, +) + +HERE = Path(__file__).resolve().parent + + +@pytest.mark.sphinx( + testroot='theming', + confoverrides={'html_theme': 'ziptheme', 'html_theme_options.testopt': 'foo'}, +) +def test_theme_api(app, status, warning): + themes = [ + 'basic', + 'default', + 'scrolls', + 'agogo', + 'sphinxdoc', + 'haiku', + 'traditional', + 'epub', + 'nature', + 'pyramid', + 'bizstyle', + 'classic', + 'nonav', + 'test-theme', + 'ziptheme', + 'staticfiles', + 'parent', + 'child', + 'alabaster', + ] + + # test Theme class API + assert set(app.registry.html_themes.keys()) == set(themes) + assert app.registry.html_themes['test-theme'] == str( + app.srcdir / 'test_theme' / 'test-theme' + ) + assert app.registry.html_themes['ziptheme'] == str(app.srcdir / 'ziptheme.zip') + assert app.registry.html_themes['staticfiles'] == str( + app.srcdir / 'test_theme' / 'staticfiles' + ) + + # test Theme instance API + theme = app.builder.theme + assert theme.name == 'ziptheme' + assert len(theme.get_theme_dirs()) == 2 + + # direct setting + assert theme.get_config('theme', 'stylesheet') == 'custom.css' + # inherited setting + assert theme.get_config('options', 'nosidebar') == 'false' + # nonexisting setting + assert theme.get_config('theme', 'foobar', 'def') == 'def' + with pytest.raises(ThemeError): + theme.get_config('theme', 'foobar') + + # options API + + options = theme.get_options({'nonexisting': 'foo'}) + assert 'nonexisting' not in options + + options = theme.get_options(app.config.html_theme_options) + assert options['testopt'] == 'foo' + assert options['nosidebar'] == 'false' + + # cleanup temp directories + theme._cleanup() + assert not any(map(os.path.exists, theme._tmp_dirs)) + + +def test_nonexistent_theme_settings(tmp_path): + # Check that error occurs with a non-existent theme.toml or theme.conf + # (https://github.com/sphinx-doc/sphinx/issues/11668) + with pytest.raises(ThemeError): + _load_theme('', str(tmp_path)) + + +@pytest.mark.sphinx(testroot='double-inheriting-theme') +def test_double_inheriting_theme(app, status, warning): + assert app.builder.theme.name == 'base_theme2' + app.build() # => not raises TemplateNotFound + + +@pytest.mark.sphinx(testroot='theming', confoverrides={'html_theme': 'child'}) +def test_nested_zipped_theme(app, status, warning): + assert app.builder.theme.name == 'child' + app.build() # => not raises TemplateNotFound + + +@pytest.mark.sphinx(testroot='theming', confoverrides={'html_theme': 'staticfiles'}) +def test_staticfiles(app, status, warning): + app.build() + assert (app.outdir / '_static' / 'staticimg.png').exists() + assert (app.outdir / '_static' / 'statictmpl.html').exists() + assert (app.outdir / '_static' / 'statictmpl.html').read_text(encoding='utf8') == ( + '<!-- testing static templates -->\n<html><project>Python</project></html>' + ) + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert '<meta name="testopt" content="optdefault" />' in result + + +@pytest.mark.sphinx(testroot='theming', confoverrides={'html_theme': 'test-theme'}) +def test_dark_style(app, monkeypatch): + monkeypatch.setattr(sphinx.builders.html, '_file_checksum', lambda o, f: '') + + style = app.builder.dark_highlighter.formatter_args.get('style') + assert style.__name__ == 'MonokaiStyle' + + app.build() + assert (app.outdir / '_static' / 'pygments_dark.css').exists() + + css_file, properties = app.registry.css_files[0] + assert css_file == 'pygments_dark.css' + assert 'media' in properties + assert properties['media'] == '(prefers-color-scheme: dark)' + + assert sorted(f.filename for f in app.builder._css_files) == [ + '_static/classic.css', + '_static/pygments.css', + '_static/pygments_dark.css', + ] + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert '<link rel="stylesheet" type="text/css" href="_static/pygments.css" />' in result + assert ( + '<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" ' + 'rel="stylesheet" type="text/css" ' + 'href="_static/pygments_dark.css" />' + ) in result + + +@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').read_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 id="searchlabel">Quick search</h3>' in result + + +@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}') + + +def test_config_file_toml(): + config_path = HERE / 'theme.toml' + cfg = _load_theme_toml(str(config_path)) + config = _convert_theme_toml(cfg) + + assert config == _ConfigFile( + stylesheets=('spam.css', 'ham.css'), + sidebar_templates=None, + pygments_style_default='spam', + pygments_style_dark=None, + options={'lobster': 'thermidor'}, + ) + + +def test_config_file_conf(): + config_path = HERE / 'theme.conf' + cfg = _load_theme_conf(str(config_path)) + config = _convert_theme_conf(cfg) + + assert config == _ConfigFile( + stylesheets=('spam.css', 'ham.css'), + sidebar_templates=None, + pygments_style_default='spam', + pygments_style_dark=None, + options={'lobster': 'thermidor'}, + ) diff --git a/tests/test_theming/theme.conf b/tests/test_theming/theme.conf new file mode 100644 index 0000000..b53fcb7 --- /dev/null +++ b/tests/test_theming/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = none +stylesheet = spam.css, ham.css +pygments_style = spam + +[options] +lobster = thermidor diff --git a/tests/test_theming/theme.toml b/tests/test_theming/theme.toml new file mode 100644 index 0000000..96a5668 --- /dev/null +++ b/tests/test_theming/theme.toml @@ -0,0 +1,10 @@ +[theme] +inherit = "none" +stylesheets = [ + "spam.css", + "ham.css", +] +pygments_style = { default = "spam" } + +[options] +lobster = "thermidor" |