microsoft / microsoft/typespec

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

Open
#9,579 0 comments 0 reactions 1 assignee Claimed by @iscai-msft View on GitHub
bug emitter:client:python
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### 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:

```python
: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 \azure-rest-api-specs\specification\ai-foundry\data-plane\Foundry`
* Run Sphinx using `tox run -e sphinx -c ../../../eng/tox/tox.ini --root . `

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] Check that this is a concrete bug. For Q&A open a [GitHub Discussion](https://github.com/Microsoft/typespec/discussions).
- [x] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.