From bba4f3da987adc26f84165c2324365a6f205501f Mon Sep 17 00:00:00 2001
From: q2mark <>
Date: Sun, 22 Jun 2025 16:12:07 -0500
Subject: [PATCH 1/2] Replace <em> with <span> for desc_annotation semantic
 HTML
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace <em class="property"> with <span class="property"> in HTML5 writer's
visit_desc_annotation and depart_desc_annotation methods to improve semantic
HTML structure for Python attribute type annotations.

Fixes #13688

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGES.rst                                   | 3 +++
 sphinx/writers/html5.py                       | 4 ++--
 tests/test_domains/test_domain_py_pyobject.py | 6 +++---
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index 0f047d6da92..c3e1d83b6c7 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -79,6 +79,9 @@ Bugs fixed
   Patch by Jean-François B.
 * #13685: gettext: Correctly ignore trailing backslashes.
   Patch by Bénédikt Tran.
+* #13688: HTML5: Replace ``<em class="property">`` with ``<span class="property">``
+  for Python attribute type annotations to improve semantic HTML structure.
+  Patch by Mark O.
 
 Testing
 -------
diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py
index 39d7ecea680..bbcd247e33c 100644
--- a/sphinx/writers/html5.py
+++ b/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>')
 
     ##############################################
 
diff --git a/tests/test_domains/test_domain_py_pyobject.py b/tests/test_domains/test_domain_py_pyobject.py
index 12b22a04dcc..dec4d71546e 100644
--- a/tests/test_domains/test_domain_py_pyobject.py
+++ b/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() == ''
 

From 7ee236c1d3633ee49ba10b1dccaee4c44fe54a30 Mon Sep 17 00:00:00 2001
From: Mark Ostroth <mark.ostroth@q2.com>
Date: Thu, 26 Jun 2025 19:22:25 -0500
Subject: [PATCH 2/2] Update AUTHORS.rst

---
 AUTHORS.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index 43a8da3469d..89b4c52cfe7 100644
--- a/AUTHORS.rst
+++ b/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