Skip to content

[Bug]: Emitted Python code with bullet-list in doc string results in Sphinx error #9579

@dargilco

Description

@dargilco

Describe the bug

This is how a property is documented in TypeSpec model:

  /**An array of content items generated by the model.
  - The length and order of items in the `output` array is dependent
  on the model's response.
  - Rather than accessing the first item in the `output` array and
  assuming it's an `assistant` message with the content generated by
  the model, you might consider using the `output_text` property where
  supported in SDKs.*/
  output: OutputItem[];

This passes TypeSpec compiler and validation.

The emitted Python code looks like this:

    :ivar output: An array of content items generated by the model.

     * The length and order of items in the `output` array is dependent
     on the model's response.
     * Rather than accessing the first item in the `output` array and
     assuming it's an `assistant` message with the content generated by
     the model, you might consider using the `output_text` property where
     supported in SDKs. Required.
    :vartype output: list[~azure.ai.projects.models.OutputItem]

Notice the blank line before the bullet list. When I run Sphinx using tox run -e sphinx -c ../../../eng/tox/tox.ini --root . I get an error docstring of azure.ai.projects.models.Response.output:4: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils] . Removing the blank line fixes the issue.

I'm using tsp-client version 0.31.0

Reproduction

Location of TypeSpec: https://github.com/Azure/azure-rest-api-specs/tree/feature/foundry-v2-spec-folder-structure/specification/ai-foundry/data-plane/Foundry (notice that it's not yet in Main branch). This TypeSpec project takes dependency on package "@azure-tools/openai-typespec": "1.8.0". The relevant TypeSpec model is named "Response" and it's defined by that package. To emit Python code:
Repro:

  • Open a command prompt in your azure-rest-api-specs repo. Switch to the branch feature/foundry-v2-spec-folder-structure and pull latest.
  • Open azure-skd-for-python repo,
  • Switch to branch feature/azure-ai-projects/2.0.0b4 and pull latest
  • cd sdk\ai\azure-ai-projects
  • Emit Python code using tsp-client update --debug --local-spec-repo <your-root>\azure-rest-api-specs\specification\ai-foundry\data-plane\Foundry
  • Run Sphinx using tox run -e sphinx -c ../../../eng/tox/tox.ini --root .

Checklist

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingemitter:client:pythonIssue for the Python client emitter: @typespec/http-client-python

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions