search

python-websockets / websockets

Library for building WebSocket servers and clients in Python
https://websockets.readthedocs.io/
BSD 3-Clause "New" or "Revised" License
5.23k stars 519 forks source link

The docs for websockets.sync.Connection.recv are not rendered correctly in VSCode #1526

Closed plorgai-ta closed 1 month ago

plorgai-ta commented 1 month ago

The docs for the recv function are not rendered correctly in VSCode. See the screenshot.

Screenshot 2024-10-18 at 2 22 14 PM

I'm not familiar with how the doc strings are written, but it appears that VSCode thinks the A is a variable name of what is returned, and is wrapping the rest of the text underneath as a description. I think it is expecting a variable name followed by a colon, which is what we see in the Raises section.

It also doesn't render the Text_ or Binary_ strings at all. These look like they are replaced by the links just below, but I'm not sure.

aaugustin commented 1 month ago

Thank you for reporting this problem.

Probably this is because VS Code doesn't understand the style of docstrings used by the project, namely https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

I want to stick to that style. I wish I could help but I don't see anything I can do. This looks more like a VS Code <> Napoleon problem than a websockets problem.