swev-id: sphinx-doc__sphinx-9258 - Support '|' union types in Python docfields (:type, :vartype) and add tests

[casey-brooks]

Summary

• Support union types with the | operator in Python docfields so each operand is linked independently.
• Add regression coverage for union docfields in parameters and vartype entries.
• Include a nitpicky test root exercising union docfields for manual reproduction.

Linked Issue

• Closes [RFE] Support union types using | in :type fields (swev-id: sphinx-doc__sphinx-9258) #72

Reproduction (before fix) on base branch (sphinx-doc__sphinx-9258)

1. Create a minimal project using tests/roots/test-domain-py-union:
   • conf.py: nitpicky = True
   • index.rst:

     .. py:function:: sample(text)
     
        :param text: textual data
        :type text: bytes | str

2. Run:

   sphinx-build -W -b html tests/roots/test-domain-py-union _build/union-html

Observed failure output (before fix)

• The entire string bytes | str is treated as a single reference target, which fails to resolve when nitpicky is enabled. Example warning:

WARNING: py:class reference target not found: bytes | str

• As a result, either a missing-reference warning appears (nitpicky), or the content renders as plain text without independent links.

Fix

• sphinx/domains/python.py: Extend PyXrefMixin.make_xrefs delimiter regex to split on | as a union delimiter (spaces around the operator).
• Does not affect existing behavior for or, commas, brackets, or ellipsis.

Tests

• tests/test_domain_py.py:
  • test_info_field_list_union_operator: verifies bytes | str, legacy str or int or None, nested generics with unions, ellipsis unions, and literal pipe non-splitting.
  • test_info_field_list_vartype_union: verifies vartype union linking.
• Manual root: tests/roots/test-domain-py-union/ for ad-hoc builds.

Local results

• Targeted tests pass locally.
• Full test run in this environment may fail due to external tool availability (e.g., ImageMagick convert) and known typing expectation diffs; this change is isolated to Python domain docfield linking and is covered by dedicated tests above.

[casey-brooks]

Test & Lint Summary

• PYTHONPATH=/workspace:/workspace/sphinx .venv/bin/pytest tests/test_domain_py.py::test_info_field_list_union_operator tests/test_domain_py.py::test_info_field_list_vartype_union
• .venv/bin/flake8 sphinx/domains/python.py tests/test_domain_py.py

Full pytest run currently fails in this pinned Sphinx 4.1 / Python 3.10 environment (missing ImageMagick convert and known typing expectation diffs).

[noa-lucent]

Summary:\n- [major] Tighten the union delimiter detection: still fires inside literals like , so we end up splitting and cross-referencing the literal pieces. Please require whitespace on both sides without breaking spacing and add regression coverage for that case.\n- Please also update to mention the new union support so the docs stay accurate.

[casey-brooks]

Test & Lint Summary

• PYTHONPATH=/workspace:/workspace/sphinx .venv/bin/pytest tests/test_domain_py.py::test_info_field_list_union_operator tests/test_domain_py.py::test_info_field_list_vartype_union
• .venv/bin/flake8 sphinx/domains/python.py tests/test_domain_py.py

Full pytest run remains flaky in this pinned Sphinx 4.1 / Python 3.10 environment (missing ImageMagick convert and known typing expectation diffs).

[noa-lucent]

Summary:

• Regex now only treats | as a union delimiter when it has whitespace on both sides, so literals like Literal['foo| bar'] stay intact.
• Regression tests cover the literal pipe case for both :type and :vartype fields.
• Documentation updated to mention the PEP 604-style union syntax and behavior for literal pipes.

Looks good to me—thanks!