1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
"""Test the Theme class."""
from __future__ import annotations
import shutil
from pathlib import Path
from typing import TYPE_CHECKING
from xml.etree.ElementTree import ParseError
import pytest
from defusedxml.ElementTree import parse as xml_parse
import sphinx.builders.html
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.errors import ThemeError
from sphinx.theming import (
_ConfigFile,
_convert_theme_conf,
_convert_theme_toml,
_load_theme,
_load_theme_conf,
_load_theme_toml,
)
if TYPE_CHECKING:
from sphinx.testing.util import SphinxTestApp
HERE = Path(__file__).resolve().parent
@pytest.mark.sphinx(
'html',
testroot='theming',
confoverrides={'html_theme': 'ziptheme', 'html_theme_options.testopt': 'foo'},
)
def test_theme_api(app: SphinxTestApp) -> None:
assert isinstance(app.builder, StandaloneHTMLBuilder) # type-checking
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'] == (
app.srcdir / 'test_theme' / 'test-theme'
)
assert app.registry.html_themes['ziptheme'] == (app.srcdir / 'ziptheme.zip')
assert app.registry.html_themes['staticfiles'] == (
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')
# nonexisting section
with pytest.raises(ThemeError):
theme.get_config('foobar', '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(p.exists() for p in 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('', tmp_path)
@pytest.mark.sphinx('html', testroot='double-inheriting-theme')
def test_double_inheriting_theme(app: SphinxTestApp) -> None:
assert isinstance(app.builder, StandaloneHTMLBuilder) # type-checking
assert app.builder.theme.name == 'base_theme2'
app.build() # => not raises TemplateNotFound
@pytest.mark.sphinx(
'html',
testroot='theming',
confoverrides={'html_theme': 'child'},
)
def test_nested_zipped_theme(app: SphinxTestApp) -> None:
assert isinstance(app.builder, StandaloneHTMLBuilder) # type-checking
assert app.builder.theme.name == 'child'
app.build() # => not raises TemplateNotFound
@pytest.mark.sphinx(
'html',
testroot='theming',
confoverrides={'html_theme': 'staticfiles'},
)
def test_staticfiles(app: SphinxTestApp) -> None:
app.build()
assert (app.outdir / '_static' / 'legacytmpl.html').exists()
assert (app.outdir / '_static' / 'legacytmpl.html').read_text(encoding='utf8') == (
'<!-- testing legacy _t static templates -->\n'
'<html><project>project name not set</project></html>'
)
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>Project name not set</project></html>'
)
result = (app.outdir / 'index.html').read_text(encoding='utf8')
assert '<meta name="testopt" content="optdefault" />' in result
@pytest.mark.sphinx(
'html',
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('html', testroot='theming')
def test_theme_sidebars(app: SphinxTestApp) -> None:
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() -> None:
config_path = HERE / 'theme.toml'
cfg = _load_theme_toml(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() -> None:
config_path = HERE / 'theme.conf'
cfg = _load_theme_conf(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'},
)
|
