def default_role(docname: str, name: str) -> Generator[None, None, None]:
if name:
dummy_reporter = Reporter('', 4, 4)
role_fn, _ = roles.role(name, english, 0, dummy_reporter)
if role_fn:
docutils.register_role('', role_fn)
else:
logger.warning(__('default role %s not found'), name, location=docname)
yield
docutils.unregister_role('')
def add_role(self, name: str, role: Any, override: bool = False) -> None:
r"""
Register a Docutils role.
The registered values are stored in the ``roles`` dictionary returned by
:func:`~sphinx_toolbox.testing.run_setup`.
(:class:`typing.Dict`\[:class:`str`\, :class:`typing.Callable`\]).
"""
if not override and docutils.is_role_registered(name):
raise ValueError(
f"role {name!r} is already registered, it will be overridden")
docutils.register_role(name, role)
def add_generic_role(self,
name: str,
nodeclass: Any,
override: bool = False) -> None:
"""
Register a generic Docutils role.
"""
if not override and docutils.is_role_registered(name):
raise ValueError(
f"role {name!r} is already registered, it will be overridden")
role = roles.GenericRole(name, nodeclass)
docutils.register_role(name, role)
def add_role(self, name: str, role: Any, override: bool = False) -> None:
"""Register a Docutils role.
*name* must be the role name that occurs in the source, *role* the role
function. Refer to the `Docutils documentation
<http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ for
more information.
.. versionchanged:: 1.8
Add *override* keyword.
"""
logger.debug('[app] adding role: %r', (name, role))
if not override and docutils.is_role_registered(name):
logger.warning(__('role %r is already registered, it will be overridden'),
name, type='app', subtype='add_role')
docutils.register_role(name, role)
def add_role(self, name, role, override=False):
# type: (str, Any, bool) -> None
"""Register a Docutils role.
*name* must be the role name that occurs in the source, *role* the role
function. Refer to the `Docutils documentation
<http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ for
more information.
.. versionchanged:: 1.8
Add *override* keyword.
"""
logger.debug('[app] adding role: %r', (name, role))
if not override and docutils.is_role_registered(name):
logger.warning(__('role %r is already registered, it will be overridden'),
name, type='app', subtype='add_role')
docutils.register_role(name, role)
def run(self) -> List[Node]:
if not self.arguments:
docutils.unregister_role('')
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role:
docutils.register_role('', role)
self.env.temp_data['default_role'] = role_name
else:
literal_block = nodes.literal_block(self.block_text, self.block_text)
reporter = self.state.reporter
error = reporter.error('Unknown interpreted text role "%s".' % role_name,
literal_block, line=self.lineno)
messages += [error]
return cast(List[nodes.Node], messages)
def add_generic_role(self, name: str, nodeclass: Any, override: bool = False) -> None:
"""Register a generic Docutils role.
Register a Docutils role that does nothing but wrap its contents in the
node given by *nodeclass*.
.. versionadded:: 0.6
.. versionchanged:: 1.8
Add *override* keyword.
"""
# Don't use ``roles.register_generic_role`` because it uses
# ``register_canonical_role``.
logger.debug('[app] adding generic role: %r', (name, nodeclass))
if not override and docutils.is_role_registered(name):
logger.warning(__('role %r is already registered, it will be overridden'),
name, type='app', subtype='add_generic_role')
role = roles.GenericRole(name, nodeclass)
docutils.register_role(name, role)
def run(self):
# type: () -> List[nodes.Node]
if not self.arguments:
docutils.unregister_role('')
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role:
docutils.register_role('', role)
self.env.temp_data['default_role'] = role_name
else:
literal_block = nodes.literal_block(self.block_text, self.block_text)
reporter = self.state.reporter
error = reporter.error('Unknown interpreted text role "%s".' % role_name,
literal_block, line=self.lineno)
messages += [error]
return cast(List[nodes.Node], messages)
def add_generic_role(self, name, nodeclass, override=False):
# type: (str, Any, bool) -> None
"""Register a generic Docutils role.
Register a Docutils role that does nothing but wrap its contents in the
node given by *nodeclass*.
.. versionadded:: 0.6
.. versionchanged:: 1.8
Add *override* keyword.
"""
# Don't use ``roles.register_generic_role`` because it uses
# ``register_canonical_role``.
logger.debug('[app] adding generic role: %r', (name, nodeclass))
if not override and docutils.is_role_registered(name):
logger.warning(__('role %r is already registered, it will be overridden'),
name, type='app', subtype='add_generic_role')
role = roles.GenericRole(name, nodeclass)
docutils.register_role(name, role)
