Add role manipulator functions to sphinx.util.docutils

sphinx/application.py

@@ -674,10 +674,10 @@ class Sphinx:
            Add *override* keyword.
         """
         logger.debug('[app] adding role: %r', (name, role))
-        if name in roles._roles and not override:
+        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')
-        roles.register_local_role(name, role)
+        docutils.register_role(name, role)
 
     def add_generic_role(self, name, nodeclass, override=False):
         # type: (unicode, Any, bool) -> None
@@ -693,11 +693,11 @@ class Sphinx:
         # Don't use ``roles.register_generic_role`` because it uses
         # ``register_canonical_role``.
         logger.debug('[app] adding generic role: %r', (name, nodeclass))
-        if name in roles._roles and not override:
+        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)
-        roles.register_local_role(name, role)
+        docutils.register_role(name, role)
 
     def add_domain(self, domain, override=False):
         # type: (Type[Domain], bool) -> None

sphinx/directives/__init__.py

@@ -15,6 +15,7 @@ from docutils import nodes
 from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
+from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer
 from sphinx.util.docutils import SphinxDirective
 
@@ -201,9 +202,7 @@ class DefaultRole(SphinxDirective):
     def run(self):
         # type: () -> List[N_co]
         if not self.arguments:
-            if '' in roles._roles:
-                # restore the "default" default role
-                del roles._roles['']
+            docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
@@ -214,7 +213,8 @@ class DefaultRole(SphinxDirective):
                 nodes.literal_block(self.block_text, self.block_text),
                 line=self.lineno)
             return messages + [error]
-        roles._roles[''] = role
+
+        docutils.register_role('', role)
         self.env.temp_data['default_role'] = role_name
         return messages
 

sphinx/util/docutils.py

@@ -67,6 +67,28 @@ def docutils_namespace():
             additional_nodes.discard(node)
 
 
+def is_role_registered(name):
+    # type: (unicode) -> bool
+    """Check the *name* role is already registered."""
+    return name in roles._roles
+
+
+def register_role(name, role):
+    # type: (unicode, RoleFunction) -> None
+    """Register a role to docutils.
+
+    This modifies global state of docutils.  So it is better to use this
+    inside ``docutils_namespace()`` to prevent side-effects.
+    """
+    roles.register_local_role(name, role)
+
+
+def unregister_role(name):
+    # type: (unicode) -> None
+    """Unregister a role from docutils."""
+    roles._roles.pop(name, None)
+
+
 def is_node_registered(node):
     # type: (Type[nodes.Element]) -> bool
     """Check the *node* is already registered."""

sphinx/util/rst.py

@@ -18,6 +18,7 @@ from docutils.parsers.rst.languages import en as english
 from docutils.utils import Reporter
 
 from sphinx.locale import __
+from sphinx.util import docutils
 from sphinx.util import logging
 
 if False:
@@ -43,10 +44,10 @@ def default_role(docname, name):
         dummy_reporter = Reporter('', 4, 4)
         role_fn, _ = roles.role(name, english, 0, dummy_reporter)
         if role_fn:
-            roles._roles[''] = role_fn
+            docutils.register_role('', role_fn)
         else:
             logger.warning(__('default role %s not found'), name, location=docname)
 
     yield
 
-    roles._roles.pop('', None)  # if a document has set a local default role
+    docutils.unregister_role('')