swev-id: sphinx-doc__sphinx-9230

[casey-brooks]

Summary

• add a balanced delimiter splitter for typed docfield arguments so type detection ignores commas inside parentheses
• add direct regression tests covering typed parameters with parenthesis/tuple syntax and autodoc reproduction
• capture autodoc docstring scenario using the same legacy type strings

Reproduction Steps

Create a function with the following docstring and build docs with autodoc:

# example.py

def f(opc_meta):
    """Example function.

    :param dict(str, str) opc_meta: (optional)
    """
    return opc_meta

conf.py:

project = 'sphinx-9230-repro'
extensions = ['sphinx.ext.autodoc']
html_theme = 'alabaster'
import os, sys
sys.path.insert(0, os.path.abspath('..'))

Build:

PYTHONPATH=/workspace/sphinx python -m sphinx.cmd.build -b html /workspace/repro-9230/source /workspace/repro-9230/build

Observed Failure (before fix)

The parameter line renders incorrectly:

str) opc_meta (dict(str,) – (optional)

Expected Behavior (after fix)

opc_meta (dict(str, str)) – (optional)

Explanation of Change

Replace whitespace split with balanced-delimiter-aware split in sphinx/util/docfields.py so spaces inside parentheses/brackets are ignored while detecting the TYPE/NAME boundary.

Stack Trace

None. This is a formatting/rendering bug; no exception is raised.

Testing

• pytest tests/test_domain_py.py -k "param_parentheses_commas or param_nested_tuple"
• pytest tests/test_ext_autodoc.py -k "docstring_typed_params"

Resolves #70

[casey-brooks]

Tests executed locally:

• pytest tests/test_domain_py.py -k "param_parentheses_commas or param_nested_tuple" (2 selected, 2 passed)
• pytest tests/test_ext_autodoc.py -k "docstring_typed_params" (1 selected, 1 passed)

All targeted suites passed; lint not applicable for these changes.

[noa-lucent]

Balanced delimiter parser correctly fixes typed docfield splitting. Tests cover regression for docfields and autodoc.