Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
changeKind: fix
packages:
- "@typespec/http-client-python"
---

Place docstring annotations such as `Required.` in front of the description when it ends with an RST code block, and stop appending a sentence period inside the block. Previously the period landed on the code block's last line (e.g. `].`) and `Required.` was appended after the block (`]. Required.`), both of which broke Sphinx rendering.
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,24 @@

from enum import Enum

from ...utils import description_ends_with_code_block

T = TypeVar("T")
OrderedSet = dict[T, None]


CODE_BLOCK_MARKER = ".. code-block::"


def add_to_description(description: str, entry: str) -> str:
if not description:
return entry
# When the description contains a code block, the entry (e.g. "Required.") must be
# inserted into the prose *before* the code block. Appending it after the code block
# (e.g. "]. Required.") leaves it dangling at the end of the rendered block and breaks
# Sphinx rendering.
if CODE_BLOCK_MARKER in description:
prose, _, code_block = description.partition(CODE_BLOCK_MARKER)
return f"{prose.rstrip()} {entry}\n\n{CODE_BLOCK_MARKER}{code_block}"
if not entry:
return description
# When the description ends with a code block, prepend the entry (e.g. "Required.") so
# it appears before the prose instead of after the block. Appending inline (e.g.
# "]. Required.") would land it inside the rendered literal block and break Sphinx, and a
# trailing paragraph reads awkwardly. The code block stays at the very end where it renders
# cleanly. (Code-block descriptions only ever carry a single annotation in practice.)
if description_ends_with_code_block(description):
return f"{entry} {description.lstrip()}"
return f"{description} {entry}"


Expand All @@ -44,6 +45,10 @@ class NamespaceType(str, Enum):

LOCALS_LENGTH_LIMIT = 25

REQUEST_BUILDER_BODY_VARIABLES_LENGTH = 6 # how many body variables are present in a request builder
REQUEST_BUILDER_BODY_VARIABLES_LENGTH = (
6 # how many body variables are present in a request builder
)

OPERATION_BODY_VARIABLES_LENGTH = 14 # how many body variables are present in an operation
OPERATION_BODY_VARIABLES_LENGTH = (
14 # how many body variables are present in an operation
)
Loading
Loading