[IMP] extensions/custom_admonitions: tweak the HTML structure of dfn

The structure of the `dfn` role is changed from its default
`<em class="dfn">text</em>` to
`<span class="dfn"><span>text</span></span>` to ease the styling.

task-3046383

Part-of: odoo/documentation#3264

extensions/custom_admonitions/__init__.py

@@ -3,6 +3,7 @@
 from docutils import nodes
 from docutils.parsers.rst.directives import admonitions
 from sphinx.locale import admonitionlabels
+from sphinx.util.docutils import SphinxRole
 
 
 class example(nodes.Admonition, nodes.Element):
@@ -21,6 +22,35 @@ class Exercise(admonitions.BaseAdmonition):
     node_class = exercise
 
 
+class Dfn(SphinxRole):
+    """ Overwrite the `dfn` role to use custom HTML. """
+
+    def run(self):
+        """ Process the content of the role.
+
+        We use custom node classes to represent the `span`s rather than the corresponding
+        sphinx.nodes.* class to prevent automatically setting the name of the node as class (e.g.,
+        "container") on the element.
+        """
+        outer_span = Span(classes=['dfn'])
+        inner_span = Span()
+        outer_span.append(inner_span)
+        text = nodes.Text(self.text)
+        inner_span.append(text)
+        return [outer_span], []
+
+
+class Span(nodes.General, nodes.Element):
+
+    @staticmethod
+    def visit(translator, node):
+        translator.body.append(translator.starttag(node, 'span').rstrip())
+
+    @staticmethod
+    def depart(translator, node):
+        translator.body.append('</span>')
+
+
 def setup(app):
     app.add_directive('example', Example)
     app.add_node(example, html=(
@@ -32,6 +62,8 @@ def setup(app):
         lambda self, node: self.visit_admonition(node, 'exercise'),
         lambda self, node: self.depart_admonition(node),
     ))
+    app.add_role('dfn', Dfn(), override=True)
+    app.add_node(Span, html=(Span.visit, Span.depart))
 
     return {
         'parallel_read_safe': True,

extensions/odoo_theme/translator.py

@@ -10,7 +10,6 @@ from sphinx.writers.html5 import HTML5Translator
 #         └── Odoo Translator
 
 ADMONITION_MAPPING = {
-# The alert classes have been replaced by default BS classes to reduce number of scss lines.
     'note': 'alert-primary',
 
     'tip': 'alert-tip',
@@ -27,7 +26,7 @@ ADMONITION_MAPPING = {
 
     'example': 'alert-success',
     'exercise': 'alert-dark',
-}
+}  # The alert classes have been replaced by default BS classes to reduce number of scss lines.
 
 
 class BootstrapTranslator(HTML5Translator):