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
|
"""Shared constants and functions."""
from __future__ import annotations
from collections.abc import Sequence
from typing import final
from docutils import nodes
from docutils.parsers.rst import directives
from sphinx.application import Sphinx
from sphinx.config import Config
from sphinx.util.docutils import SphinxDirective
from sphinx.util.logging import getLogger
LOGGER = getLogger(__name__)
WARNING_TYPE = "design"
SEMANTIC_COLORS = (
"primary",
"secondary",
"success",
"info",
"warning",
"danger",
"light",
"muted",
"dark",
"white",
"black",
)
def setup_custom_directives(
app: Sphinx, config: Config, directive_map: dict[str, SdDirective]
) -> None:
conf_value = config.sd_custom_directives
def _warn(msg):
LOGGER.warning(
f"sd_custom_directives: {msg}", type=WARNING_TYPE, subtype="config"
)
if not isinstance(conf_value, dict):
_warn("must be a dictionary")
config.sd_custom_directives = {}
return
for name, data in conf_value.items():
if not isinstance(name, str):
_warn(f"key must be a string: {name!r}")
continue
if not isinstance(data, dict):
_warn(f"{name!r} value must be a dictionary")
continue
if "inherit" not in data:
_warn(f"{name!r} value must have an 'inherit' key")
continue
if data["inherit"] not in directive_map:
_warn(f"'{name}.inherit' is an unknown directive key: {data['inherit']}")
continue
directive_cls = directive_map[data["inherit"]]
if "options" in data:
if not isinstance(data["options"], dict):
_warn(f"'{name}.options' value must be a dictionary")
continue
if "argument" in data and not isinstance(data["argument"], str):
_warn(f"'{name}.argument' value must be a string")
continue
for key, value in data["options"].items():
if key not in directive_cls.option_spec:
_warn(f"'{name}.options' unknown key {key!r}")
continue
if not isinstance(value, str):
_warn(f"'{name}.options.{key}' value must be a string")
continue
app.add_directive(name, directive_cls, override=True)
class SdDirective(SphinxDirective):
"""Base class for all sphinx-design directives.
Having a base class allows for shared functionality to be implemented in one place.
Namely, we allow for default options to be configured, per directive name.
This class should be sub-classed by all directives in the sphinx-design extension.
"""
# TODO perhaps ideally there would be separate sphinx extension,
# that generalises the concept of default directive options (that does not require subclassing)
# but for now I couldn't think of a trivial way to achieve this.
@final
def run(self) -> list[nodes.Node]:
"""Run the directive.
This method should not be overridden, instead override `run_with_defaults`.
"""
if data := self.config.sd_custom_directives.get(self.name):
if (not self.arguments) and (argument := data.get("argument")): # type: ignore[has-type]
self.arguments = [str(argument)]
for key, value in data.get("options", {}).items():
if key not in self.options and key in self.option_spec:
try:
self.options[key] = self.option_spec[key](str(value))
except Exception as exc:
LOGGER.warning(
f"Invalid default option {key!r} for {self.name!r}: {exc}",
type=WARNING_TYPE,
subtype="directive",
location=(self.env.docname, self.lineno),
)
return self.run_with_defaults()
def run_with_defaults(self) -> list[nodes.Node]:
"""Run the directive, after default options have been set.
This method should be overridden by subclasses.
"""
raise NotImplementedError
def create_component(
name: str,
classes: Sequence[str] = (),
*,
rawtext: str = "",
children: Sequence[nodes.Node] = (),
**attributes,
) -> nodes.container:
"""Create a container node for a design component."""
node = nodes.container(
rawtext, is_div=True, design_component=name, classes=list(classes), **attributes
)
node.extend(children)
return node
def is_component(node: nodes.Node, name: str):
"""Check if a node is a certain design component."""
try:
return node.get("design_component") == name
except AttributeError:
return False
def make_choice(choices: Sequence[str]):
"""Create a choice validator."""
return lambda argument: directives.choice(argument, choices)
def _margin_or_padding_option(
argument: str | None,
class_prefix: str,
allowed: Sequence[str],
) -> list[str]:
"""Validate the margin/padding is one (all) or four (top bottom left right) integers,
between 0 and 5 or 'auto'.
"""
if argument is None:
raise ValueError("argument required but none supplied")
values = argument.split()
for value in values:
if value not in allowed:
raise ValueError(f"{value} is not in: {allowed}")
if len(values) == 1:
return [f"{class_prefix}-{values[0]}"]
if len(values) == 4:
return [
f"{class_prefix}{side}-{value}"
for side, value in zip(["t", "b", "l", "r"], values, strict=False)
]
raise ValueError(
"argument must be one (all) or four (top bottom left right) integers"
)
def margin_option(argument: str | None) -> list[str]:
"""Validate the margin is one (all) or four (top bottom left right) integers,
between 0 and 5 or 'auto'.
"""
return _margin_or_padding_option(
argument, "sd-m", ("auto", "0", "1", "2", "3", "4", "5")
)
def padding_option(argument: str | None) -> list[str]:
"""Validate the padding is one (all) or four (top bottom left right) integers,
between 0 and 5.
"""
return _margin_or_padding_option(argument, "sd-p", ("0", "1", "2", "3", "4", "5"))
def text_align(argument: str | None) -> list[str]:
"""Validate the text align is left, right, center or justify."""
value = directives.choice(argument, ["left", "right", "center", "justify"])
return [f"sd-text-{value}"]
class PassthroughTextElement(nodes.TextElement):
"""A text element which will not render anything.
This is required for reference node to render correctly outside of paragraphs.
Since sphinx expects them to be within a ``TextElement``:
https://github.com/sphinx-doc/sphinx/blob/068f802df90ea790f89319094e407c4d5f6c26ff/sphinx/writers/html5.py#L224
"""
|
