Use <span> in desc_annotation for better semantic HTML (sphinx-doc#13689)

Co-authored-by: Adam Turner <[email protected]>

Author: q2mark

AUTHORS.rst

@@ -83,6 +83,7 @@ Contributors
 * Louis Maddox -- better docstrings
 * Łukasz Langa -- partial support for autodoc
 * Marco Buttu -- doctest extension (pyversion option)
+* Mark Ostroth -- semantic HTML contributions
 * Martin Hans -- autodoc improvements
 * Martin Larralde -- additional napoleon admonitions
 * Martin Liška -- option directive and role improvements

CHANGES.rst

@@ -97,6 +97,11 @@ Bugs fixed
   Patch by Bénédikt Tran.
 * #13712: intersphinx: Don't add "v" prefix to non-numeric versions.
   Patch by Szymon Karpinski.
+* #13688: HTML builder: Replace ``<em class="property">`` with
+  ``<span class="property">`` for attribute type annotations
+  to improve `semantic HTML structure
+  <https://html.spec.whatwg.org/multipage/text-level-semantics.html>`__.
+  Patch by Mark Ostroth.
 
 Testing
 -------

sphinx/writers/html5.py

@@ -305,10 +305,10 @@ def depart_desc_optional(self, node: Element) -> None:
             self.param_group_index += 1
 
     def visit_desc_annotation(self, node: Element) -> None:
-        self.body.append(self.starttag(node, 'em', '', CLASS='property'))
+        self.body.append(self.starttag(node, 'span', '', CLASS='property'))
 
     def depart_desc_annotation(self, node: Element) -> None:
-        self.body.append('</em>')
+        self.body.append('</span>')
 
     ##############################################
 

tests/test_domains/test_domain_py_pyobject.py

@@ -925,17 +925,17 @@ def test_domain_py_type_alias(app):
 
     content = (app.outdir / 'type_alias.html').read_text(encoding='utf8')
     assert (
-        '<em class="property"><span class="k"><span class="pre">type</span></span><span class="w"> </span></em>'
+        '<span class="property"><span class="k"><span class="pre">type</span></span><span class="w"> </span></span>'
         '<span class="sig-prename descclassname"><span class="pre">module_one.</span></span>'
         '<span class="sig-name descname"><span class="pre">MyAlias</span></span>'
-        '<em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span>'
+        '<span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span>'
         '<span class="w"> </span><span class="pre">list</span>'
         '<span class="p"><span class="pre">[</span></span>'
         '<span class="pre">int</span><span class="w"> </span>'
         '<span class="p"><span class="pre">|</span></span><span class="w"> </span>'
         '<a class="reference internal" href="#module_two.SomeClass" title="module_two.SomeClass">'
         '<span class="pre">module_two.SomeClass</span></a>'
-        '<span class="p"><span class="pre">]</span></span></em>'
+        '<span class="p"><span class="pre">]</span></span></span>'
     ) in content
     assert app.warning.getvalue() == ''