Roles

Summary

Package:

pyTooling.Sphinx

Doc-string:

documented

File

Expected

Covered

Uncovered

Coverage

Roles.py

7

7

0

100.0%

Source

pyTooling.Sphinx/Roles.pydocumentedundocumentedignoredexcludednot counted
31"""
32The ReST roles shared by pyTooling's documentation and its sibling projects.
33
34Every project used to declare these in its own :file:`doc/prolog.inc`, as ReST source re-parsed into every document
35of every project - and eighteen hand-copied files had already drifted apart. Registering them from an extension
36makes one declaration serve all of them, and puts the styling in a stylesheet instead of a ``raw:: html`` block.
37
38.. seealso::
39
40   :mod:`pyTooling.Sphinx`
41      |rarr| The extension registering these, and what else it brings.
42"""
...
51
53__all__ = ["STYLE_ROLES", "PYTHON_CODE_ROLE", "BREAK_ROLES"]
54
55#: The style roles, mapping a role's name to the CSS classes it applies.
56STYLE_ROLES = {
57	"bolditalic": ("bolditalic", ),
58	"underline":  ("underline", ),
59	"strike":     ("strike", ),
60	"xlarge":     ("xlarge", ),
61	"red":        ("colorred", ),
62	"green":      ("colorgreen", ),
63	"blue":       ("colorblue", ),
64	"purple":     ("colorpurple", ),
65	"deletion":   ("colorred", "strike"),
66	"addition":   ("colorgreen", ),
67}
68
69#: Name of the role rendering inline Python code.
70PYTHON_CODE_ROLE = "pycode"
71
72#: The break roles, mapping a role's name to what each output format writes for it.
73#:
74#: A :class:`~docutils.nodes.raw` node carries the format it is meant for and a writer ignores every other one, so
75#: emitting all of them lets each builder pick its own. That is what makes ``|br|`` work outside HTML.
76BREAK_ROLES = {
77	"br": {"html": "<br />",  "latex": r"\\"},
78	"hr": {"html": "<hr />",  "latex": r"\par\noindent\rule{\textwidth}{0.4pt}\par"},
79}
80
82@export
83def styleRole(
84	name: str,
85	rawText: str,
86	text: str,
87	lineNumber: int,
88	inliner: Inliner,
89	options: Nullable[dict[str, Any]] = None,
90	content: Nullable[list[str]] = None
91) -> tuple[list[nodes.Node], list[nodes.system_message]]:
92	"""
93	Render inline text with the CSS classes registered for the role's name.
94
95	This is what ``.. role:: red`` with ``:class: colorred`` does in a prolog, without the prolog: the role's name is
96	looked up in :data:`STYLE_ROLES` and the classes it maps to are put on an :class:`~docutils.nodes.inline` node.
97
98	:param name:       Name the role was invoked by, which is what selects the classes.
99	:param rawText:    The role's text including its markup.
100	:param text:       The role's text with the markup removed.
101	:param lineNumber: Line the role was used on.
102	:param inliner:    The inliner that called this role.
103	:param options:    Options given to the role; unused, because the classes come from the role's name.
104	:param content:    Content given to the role; unused.
105	:returns:          Tuple of the produced nodes and the system messages, as a docutils role returns.
106	"""
	...
110
112@export
113def pythonCodeRole(
114	name: str,
115	rawText: str,
116	text: str,
117	lineNumber: int,
118	inliner: Inliner,
119	options: Nullable[dict[str, Any]] = None,
120	content: Nullable[list[str]] = None
121) -> tuple[list[nodes.Node], list[nodes.system_message]]:
122	r"""
123	Render inline Python code, syntax-highlighted.
124
125	The docutils ``code`` role does the work; this fixes its language to Python and adds the ``highlight`` class, so
126	a page writes ``:pycode:`isinstance(x, int)``` instead of repeating the options at every use.
127
128	:param name:       Name the role was invoked by; unused, because the language is fixed.
129	:param rawText:    The role's text including its markup.
130	:param text:       The role's text with the markup removed.
131	:param lineNumber: Line the role was used on.
132	:param inliner:    The inliner that called this role.
133	:param options:    Options given to the role; replaced by the fixed ones.
134	:param content:    Content given to the role, handed to the ``code`` role unchanged.
135	:returns:          Tuple of the produced nodes and the system messages, as a docutils role returns.
136	"""
	...
140
142@export
143def breakRole(
144	name: str,
145	rawText: str,
146	text: str,
147	lineNumber: int,
148	inliner: Inliner,
149	options: Nullable[dict[str, Any]] = None,
150	content: Nullable[list[str]] = None
151) -> tuple[list[nodes.Node], list[nodes.system_message]]:
152	"""
153	Emit a line or a horizontal break in every output format that has one.
154
155	A :class:`~docutils.nodes.raw` node names the format it is for, and a writer skips the ones that aren't its own -
156	so one node per format is emitted and each builder takes what it understands. Written as a ``raw:: html`` block,
157	which is what these were before, a break reached HTML and nothing else.
158
159	:param name:       Name the role was invoked by, which selects what is written.
160	:param rawText:    The role's text including its markup.
161	:param text:       The role's text with the markup removed; unused, a break has no content.
162	:param lineNumber: Line the role was used on.
163	:param inliner:    The inliner that called this role.
164	:param options:    Options given to the role; unused.
165	:param content:    Content given to the role; unused.
166	:returns:          Tuple of the produced nodes and the system messages, as a docutils role returns.
167	"""
	...