Python
/
ruff
mirror of https://github.com/astral-sh/ruff
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[ty] Implement docstring rendering to markdown (#21550) 

## Summary

This introduces a very bad and naive
python-docstring-flavoured-reStructuredText to github-flavor-markdown
translator. The main goal is to try to preserve a lot of the formatting
and plaintext, progressively enhance the content when we find things we
know about, and escape the text when we find things that might get
corrupt.

Previously I'd broken this out into rendering each different format, but
with this approach you don't really need to?

## Test Plan

Lots of snapshot tests, also messed around in some random stdlib
modules.
This commit is contained in:
Aria Desires 2025-11-21 10:47:38 -05:00 committed by GitHub
parent 762c44527e
commit 629258241f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 904 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1007
crates/ty_ide/src/docstring.rs
View File

File diff suppressed because it is too large Load Diff

122
crates/ty_ide/src/hover.rs
View File

@ -245,14 +245,11 @@ mod tests {
) -> Unknown ) -> Unknown
``` ```
--- ---
```text This is such a great func!!
This is such a great func!!
Args:
Args:     a: first for a reason
a: first for a reason     b: coming for `a`'s title
b: coming for `a`'s title
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:11:1 --> main.py:11:1
@ -303,14 +300,11 @@ mod tests {
) -> Unknown ) -> Unknown
``` ```
--- ---
```text This is such a great func!!
This is such a great func!!
Args:
Args:     a: first for a reason
a: first for a reason     b: coming for `a`'s title
b: coming for `a`'s title
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:2:5 --> main.py:2:5
@ -369,14 +363,11 @@ mod tests {
<class 'MyClass'> <class 'MyClass'>
``` ```
--- ---
```text This is such a great class!!
This is such a great class!!
&nbsp;&nbsp;&nbsp;&nbsp;Don't you know?
Don't you know?
Everyone loves my class!! Everyone loves my class!!
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:24:1 --> main.py:24:1
@ -434,14 +425,11 @@ mod tests {
<class 'MyClass'> <class 'MyClass'>
``` ```
--- ---
```text This is such a great class!!
This is such a great class!!
&nbsp;&nbsp;&nbsp;&nbsp;Don't you know?
Don't you know?
Everyone loves my class!! Everyone loves my class!!
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:2:7 --> main.py:2:7
@ -497,10 +485,7 @@ mod tests {
<class 'MyClass'> <class 'MyClass'>
``` ```
--- ---
```text
initializes MyClass (perfectly) initializes MyClass (perfectly)
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:24:5 --> main.py:24:5
@ -556,10 +541,7 @@ mod tests {
<class 'MyClass'> <class 'MyClass'>
``` ```
--- ---
```text
initializes MyClass (perfectly) initializes MyClass (perfectly)
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:11 --> main.py:4:11
@ -618,14 +600,11 @@ mod tests {
<class 'MyClass'> <class 'MyClass'>
``` ```
--- ---
```text This is such a great class!!
This is such a great class!!
&nbsp;&nbsp;&nbsp;&nbsp;Don't you know?
Don't you know?
Everyone loves my class!! Everyone loves my class!!
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:23:5 --> main.py:23:5
@ -692,14 +671,11 @@ mod tests {
) -> Unknown ) -> Unknown
``` ```
--- ---
```text This is such a great func!!
This is such a great func!!
Args:
Args: &nbsp;&nbsp;&nbsp;&nbsp;a: first for a reason
a: first for a reason &nbsp;&nbsp;&nbsp;&nbsp;b: coming for `a`'s title
b: coming for `a`'s title
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:25:3 --> main.py:25:3
@ -973,10 +949,7 @@ def ab(a: str): ...
(a: int) -> Unknown (a: int) -> Unknown
``` ```
--- ---
```text
the int overload the int overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1036,10 +1009,7 @@ def ab(a: str):
(a: str) -> Unknown (a: str) -> Unknown
``` ```
--- ---
```text
the int overload the int overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1105,10 +1075,7 @@ def ab(a: int):
) -> Unknown ) -> Unknown
``` ```
--- ---
```text
the two arg overload the two arg overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1168,10 +1135,7 @@ def ab(a: int):
(a: int) -> Unknown (a: int) -> Unknown
``` ```
--- ---
```text
the two arg overload the two arg overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1243,10 +1207,7 @@ def ab(a: int, *, c: int):
) -> Unknown ) -> Unknown
``` ```
--- ---
```text
keywordless overload keywordless overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1318,10 +1279,7 @@ def ab(a: int, *, c: int):
) -> Unknown ) -> Unknown
``` ```
--- ---
```text
keywordless overload keywordless overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1386,10 +1344,7 @@ def ab(a: int, *, c: int):
) -> Unknown ) -> Unknown
``` ```
--- ---
```text
The first overload The first overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:19:1 --> main.py:19:1
@ -1441,10 +1396,7 @@ def ab(a: int, *, c: int):
(a: str) -> Unknown (a: str) -> Unknown
``` ```
--- ---
```text
The first overload The first overload
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:19:1 --> main.py:19:1
@ -1494,12 +1446,9 @@ def ab(a: int, *, c: int):
<module 'lib'> <module 'lib'>
``` ```
--- ---
```text The cool lib/_py module!
The cool lib_py module!
Wow this module rocks. Wow this module rocks.
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:4:1 --> main.py:4:1
@ -1544,12 +1493,9 @@ def ab(a: int, *, c: int):
Wow this module rocks. Wow this module rocks.
--------------------------------------------- ---------------------------------------------
```text The cool lib/_py module!
The cool lib_py module!
Wow this module rocks. Wow this module rocks.
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:2:8 --> main.py:2:8
@ -2499,10 +2445,7 @@ def ab(a: int, *, c: int):
bound method int.__add__(value: int, /) -> int bound method int.__add__(value: int, /) -> int
``` ```
--- ---
```text
Return self+value. Return self+value.
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:2:12 --> main.py:2:12
@ -2618,10 +2561,7 @@ def ab(a: int, *, c: int):
int | float int | float
``` ```
--- ---
```text
Convert a string or number to a floating-point number, if possible. Convert a string or number to a floating-point number, if possible.
```
--------------------------------------------- ---------------------------------------------
info[hover]: Hovered content is info[hover]: Hovered content is
--> main.py:2:4 --> main.py:2:4