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