[python] Fix Sphinx docstring rendering of annotations after code blocks

[l0lawrence]

Why

Fixes microsoft#10314. When a property or parameter description ended with a code block, the emitter appended annotations like Required. to the very end of the string. With code blocks converted to RST .. code-block::, the annotation landed right after the closing ] of a JSON block (]. Required.), which breaks Sphinx rendering. This was one of the issues being worked around in @dargilco's post-processing script.

Approach

The annotations are added centrally in add_to_description (in pygen/codegen/models/utils.py), which is used by both property.py and parameter.py (and other callers). I made that helper code-block aware: when the description contains .. code-block::, the annotation is now inserted into the prose before the code block instead of being appended after it. Behavior is unchanged when there is no code block.

This is a minimal, central fix so every caller benefits without touching individual call sites.

Tests

Added tests/unit/test_add_to_description.py covering the empty, plain, single-code-block, and multiple-code-block cases. The multi-block case verifies insertion happens before the first block.

Note: 3 pre-existing unit failures in test_model_base_serialization.py / test_model_base_xml_serialization.py are unrelated to this change.

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http-client-python

Show changes

@typespec/http-client-python - fix ✏️

Fix Sphinx docstring rendering when a Required. (or other) annotation followed a code block. The annotation is now inserted into the prose before the code block instead of being appended after it.

[l0lawrence]

Superseded by a PR targeting microsoft/typespec main.