Skip to content

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

Merged
Yuchao Yan (msyyc) merged 3 commits into
microsoft:mainfrom
l0lawrence:l0lawrence/sphinx-required-codeblock
Jun 12, 2026
Merged

Yuchao Yan (msyyc) merged 3 commits into
microsoft:mainfrom
l0lawrence:l0lawrence/sphinx-required-codeblock

Conversation

@l0lawrence

Copy link
Copy Markdown
Member

Why

Fixes #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.

Approach

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

Tests

Added tests/unit/test_add_to_description.py covering the empty, plain, single-code-block, and multiple-code-block cases.

…strings

Required. and other annotations were appended after RST code blocks, breaking Sphinx rendering. They are now inserted into the prose before the code block.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added the emitter:client:python Issue for the Python client emitter: @typespec/http-client-python label Jun 10, 2026
@pkg-pr-new

pkg-pr-new Bot commented Jun 10, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-python@10955

commit: 4293828

@github-actions

github-actions Bot commented Jun 10, 2026 •

Copy link
Copy Markdown
Contributor

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.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@azure-sdk-automation

azure-sdk-automation Bot commented Jun 10, 2026 •

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

@l0lawrence

Copy link
Copy Markdown
Member Author

@msyyc
Yuchao Yan (msyyc) added this pull request to the merge queue Jun 12, 2026
Merged via the queue into microsoft:main with commit c018877 Jun 12, 2026
41 checks passed
Libba Lawrence (l0lawrence) added a commit to l0lawrence/typespec that referenced this pull request Jun 18, 2026
…iling code blocks (microsoft#11013)

## Why

Follow-up to microsoft#10955. That change kept the broken `]. Required.` from
rendering, but two related issues remained for docstrings whose
description ends with an RST code block (e.g. `ToolChoiceAllowed.tools`
in `azure-ai-projects`):

1. `Required.` was inserted into the prose right before the code block,
so it landed on the lead-in sentence: `...might look like: Required.`
followed by the block. That reads wrong.
2. `preprocess.update_description` still appended a sentence-ending `.`
to the description, which landed on the code block's last content line
(`]` -> `].`), corrupting the rendered literal block.

## What

- Add a shared `description_ends_with_code_block` helper (in
`pygen/utils.py`) that detects when a code block is the trailing content
of a description.
- `add_to_description`: when the description ends with a code block,
append the annotation (`Required.`, default value, etc.) as its own
paragraph **after** the block instead of inline. Chained annotations
group onto that trailing paragraph. Behavior is unchanged when there is
no trailing code block, or when prose follows the block.
- `update_description`: skip the trailing-period append when the
description ends with a code block, so no `.` is injected into the
block.

## Result

For `ToolChoiceAllowed.tools`:

`
:ivar tools: A list of tool definitions ... might look like:

   .. code-block:: json

      [ ... ]

   Required.
`

No `].` inside the block, and `Required.` sits cleanly on its own line.

Covered by unit tests in `tests/unit/test_add_to_description.py` (10
tests, including the full `update_description` -> `add_to_description`
pipeline).

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

emitter:client:python Issue for the Python client emitter: @typespec/http-client-python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[python] sphinx doctoring formatting of Required

2 participants