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
|
"""Test the documented snippets run correctly, and are the same for both RST and MyST."""
from pathlib import Path
from typing import Callable
import pytest
from .conftest import SphinxBuilder
try:
import myst_parser # noqa: F401
MYST_INSTALLED = True
except ImportError:
MYST_INSTALLED = False
SNIPPETS_PATH = Path(__file__).parent.parent / "docs" / "snippets"
SNIPPETS_GLOB_RST = list((SNIPPETS_PATH / "rst").glob("[!_]*"))
SNIPPETS_GLOB_MYST = list((SNIPPETS_PATH / "myst").glob("[!_]*"))
def write_assets(src_path: Path):
"""Write additional assets to the src directory."""
src_path.joinpath("snippet.py").write_text("a = 1")
src_path.joinpath("images").mkdir()
src_path.joinpath("images", "ebp-logo.png").touch()
src_path.joinpath("images", "particle_background.jpg").touch()
@pytest.mark.parametrize(
"path",
SNIPPETS_GLOB_RST,
ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_RST],
)
def test_snippets_rst(
sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
):
"""Test snippets written in RestructuredText (before post-transforms)."""
builder = sphinx_builder(conf_kwargs={"extensions": ["sphinx_design"]})
content = "Heading\n-------" + "\n\n" + path.read_text(encoding="utf8")
builder.src_path.joinpath("index.rst").write_text(content, encoding="utf8")
write_assets(builder.src_path)
builder.build()
doctree = builder.get_doctree("index", post_transforms=False)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename=f"snippet_pre_{path.name[:-len(path.suffix)]}",
extension=".xml",
encoding="utf8",
)
@pytest.mark.parametrize(
"path",
SNIPPETS_GLOB_MYST,
ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_MYST],
)
@pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
def test_snippets_myst(
sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
):
"""Test snippets written in MyST Markdown (before post-transforms)."""
builder = sphinx_builder()
content = "# Heading" + "\n\n\n" + path.read_text(encoding="utf8")
builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
write_assets(builder.src_path)
builder.build()
doctree = builder.get_doctree("index", post_transforms=False)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename=f"snippet_pre_{path.name[:-len(path.suffix)]}",
extension=".xml",
encoding="utf8",
)
@pytest.mark.parametrize(
"path",
SNIPPETS_GLOB_RST,
ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_RST],
)
def test_snippets_rst_post(
sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
):
"""Test snippets written in RestructuredText (after HTML post-transforms)."""
builder = sphinx_builder(conf_kwargs={"extensions": ["sphinx_design"]})
content = "Heading\n-------" + "\n\n" + path.read_text(encoding="utf8")
builder.src_path.joinpath("index.rst").write_text(content, encoding="utf8")
write_assets(builder.src_path)
builder.build()
doctree = builder.get_doctree("index", post_transforms=True)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename=f"snippet_post_{path.name[:-len(path.suffix)]}",
extension=".xml",
encoding="utf8",
)
@pytest.mark.parametrize(
"path",
SNIPPETS_GLOB_MYST,
ids=[path.name[: -len(path.suffix)] for path in SNIPPETS_GLOB_MYST],
)
@pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
def test_snippets_myst_post(
sphinx_builder: Callable[..., SphinxBuilder], path: Path, file_regression
):
"""Test snippets written in MyST Markdown (after HTML post-transforms)."""
builder = sphinx_builder()
content = "# Heading" + "\n\n\n" + path.read_text(encoding="utf8")
builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
write_assets(builder.src_path)
builder.build()
doctree = builder.get_doctree("index", post_transforms=True)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename=f"snippet_post_{path.name[:-len(path.suffix)]}",
extension=".xml",
encoding="utf8",
)
def test_sd_hide_title_rst(
sphinx_builder: Callable[..., SphinxBuilder], file_regression
):
"""Test that the root title is hidden."""
builder = sphinx_builder(conf_kwargs={"extensions": ["sphinx_design"]})
content = ":sd_hide_title:\n\nHeading\n-------\n\ncontent"
builder.src_path.joinpath("index.rst").write_text(content, encoding="utf8")
builder.build()
doctree = builder.get_doctree("index", post_transforms=False)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename="sd_hide_title",
extension=".xml",
encoding="utf8",
)
@pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
def test_sd_hide_title_myst(
sphinx_builder: Callable[..., SphinxBuilder], file_regression
):
"""Test that the root title is hidden."""
builder = sphinx_builder()
content = "---\nsd_hide_title: true\n---\n\n# Heading\n\ncontent"
builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
builder.build()
doctree = builder.get_doctree("index", post_transforms=False)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename="sd_hide_title",
extension=".xml",
encoding="utf8",
)
@pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
def test_sd_custom_directives(
sphinx_builder: Callable[..., SphinxBuilder], file_regression
):
"""Test that the defaults are used."""
builder = sphinx_builder(
conf_kwargs={
"extensions": ["myst_parser", "sphinx_design"],
"sd_custom_directives": {
"dropdown-syntax": {
"inherit": "dropdown",
"argument": "Syntax",
"options": {
"color": "primary",
"icon": "code",
},
}
},
}
)
content = "# Heading\n\n```{dropdown-syntax}\ncontent\n```"
builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
builder.build()
doctree = builder.get_doctree("index", post_transforms=False)
doctree.attributes.pop("translation_progress", None) # added in sphinx 7.1
file_regression.check(
doctree.pformat(),
basename="sd_custom_directives",
extension=".xml",
encoding="utf8",
)
|
