tags, which creates inappropriate semantic HTML where punctuation (colons, equals signs)...">

Python attribute type annotations use inappropriate tags, breaking semantic HTML (original) (raw)

Problem

Sphinx currently wraps Python attribute type annotations and default values in <em class="property"> tags, which creates inappropriate semantic HTML where punctuation (colons, equals signs) and type information are italicized.

Current Behavior

For a Python attribute like:

.. py:attribute:: name :type: str :value: "default_value"

Sphinx generates:

name : str = "default_value"

Issues This Causes

  1. Poor semantic HTML: Punctuation (: and =) shouldn't be emphasized
  2. Visual problems: Colons and equals signs appear italicized in browsers
  3. Markdown conversion issues: Documentation crawlers/converters produce messy output like:
name*: `str`* *= "default_value"*
  1. Accessibility concerns: Screen readers may interpret emphasis incorrectly

Expected Behavior

Type annotations should use <span class="property"> instead of <em class="property">:

name : str = "default_value"

Environment

Root Cause

The issue is in sphinx/writers/html5.py lines 307-311:

def visit_desc_annotation(self, node: Element) -> None: self.body.append(self.starttag(node, 'em', '', CLASS='property'))

def depart_desc_annotation(self, node: Element) -> None: self.body.append('')

Proposed Solution

Replace em with span to maintain CSS styling while fixing semantic HTML:

def visit_desc_annotation(self, node: Element) -> None: self.body.append(self.starttag(node, 'span', '', CLASS='property'))

def depart_desc_annotation(self, node: Element) -> None: self.body.append('')

Additional Context

This aligns with Sphinx's recent efforts to improve semantic HTML structure, similar to the work done in issues #4390 (consistent CSS for signatures) and #13454 (CSS classes for method types).