Skip to content

Commit 1f83cf4

Browse files
lerebearlerebear
committed
Render Google docstring sections through parsed blocks
1 parent 1703c7a commit 1f83cf4

5 files changed

Lines changed: 1102 additions & 59 deletions

File tree

‎crates/ty_ide/src/docstring.rs‎

Lines changed: 179 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -865,6 +865,141 @@ mod tests {
865865
"#);
866866
}
867867

868+
#[test]
869+
fn google_sections_render_edge_cases() {
870+
let _snap = bind_docstring_snapshot_filters();
871+
let docstring = Docstring::new(
872+
"\
873+
Attributes:
874+
name (str): Display name.
875+
coords (tuple(int, int)): Coordinate pair.
876+
callback (Callable(int, str)): Converts raw values.
877+
if name:
878+
return name
879+
880+
Raises:
881+
ValueError: If invalid."
882+
.to_owned(),
883+
);
884+
885+
assert_snapshot!(docstring.render_markdown(), @"
886+
## Attributes<HB>
887+
`name` (`str`): Display name.<HB>
888+
`coords` (`tuple(int, int)`): Coordinate pair.<HB>
889+
`callback` (`Callable(int, str)`): Converts raw values.<HB>
890+
&nbsp;&nbsp;&nbsp;&nbsp;if name:<HB>
891+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return name<HB>
892+
<HB>
893+
## Raises<HB>
894+
`ValueError`: If invalid.
895+
");
896+
897+
let docstring = Docstring::new(
898+
"\
899+
Args:
900+
value: Description.
901+
```python
902+
Args:
903+
nested: Still code.
904+
Returns:
905+
Still code.
906+
```
907+
url (Literal[\"http://\"]): URL."
908+
.to_owned(),
909+
);
910+
911+
assert_snapshot!(docstring.render_markdown(), @r#"
912+
## Parameters<HB>
913+
`value`: Description.<HB>
914+
<HB>
915+
```python
916+
Args:
917+
nested: Still code.
918+
Returns:
919+
Still code.
920+
```<HB>
921+
`url` (`Literal["http://"]`): URL.
922+
"#);
923+
924+
let docstring = Docstring::new(
925+
"\
926+
Summary.
927+
928+
Returns:
929+
Literal[\"http://\"]: First paragraph.
930+
931+
Second paragraph."
932+
.to_owned(),
933+
);
934+
935+
assert_snapshot!(docstring.render_markdown(), @r#"
936+
Summary.<HB>
937+
<HB>
938+
## Returns<HB>
939+
`Literal["http://"]`: First paragraph.<HB>
940+
&nbsp;&nbsp;&nbsp;&nbsp;<HB>
941+
&nbsp;&nbsp;&nbsp;&nbsp;Second paragraph.
942+
"#);
943+
944+
let docstring = Docstring::new(
945+
"\
946+
Summary.
947+
948+
Args:
949+
value: Description.
950+
>>> value
951+
42"
952+
.to_owned(),
953+
);
954+
955+
assert_snapshot!(docstring.render_markdown(), @"
956+
Summary.<HB>
957+
<HB>
958+
## Parameters<HB>
959+
`value`: Description.<HB>
960+
```````````python
961+
>>> value
962+
42
963+
```````````
964+
");
965+
966+
let docstring = Docstring::new(
967+
"\
968+
Returns:
969+
https://example.com: more details."
970+
.to_owned(),
971+
);
972+
973+
assert_snapshot!(docstring.render_markdown(), @"
974+
## Returns<HB>
975+
https://example.com: more details.
976+
");
977+
978+
let docstring = Docstring::new(
979+
"\
980+
Returns:
981+
str:Description without whitespace."
982+
.to_owned(),
983+
);
984+
985+
assert_snapshot!(docstring.render_markdown(), @"
986+
## Returns<HB>
987+
`str`: Description without whitespace.
988+
");
989+
990+
let docstring = Docstring::new(
991+
"\
992+
Args:
993+
: Missing name."
994+
.to_owned(),
995+
);
996+
997+
assert_snapshot!(docstring.render_markdown(), @"
998+
Args:<HB>
999+
: Missing name.
1000+
");
1001+
}
1002+
8681003
// A literal block where the `::` is flush with the paragraph
8691004
// and should become `:`
8701005
#[test]
@@ -1259,14 +1394,15 @@ mod tests {
12591394
assert_snapshot!(docstring.render_markdown(), @"
12601395
My cool func...<HB>
12611396
<HB>
1262-
Returns:<HB>
1263-
&nbsp;&nbsp;&nbsp;&nbsp;Some details<HB>
1397+
## Returns<HB>
1398+
Some details<HB>
1399+
<HB>
12641400
`````python
1265-
x_y = thing_do();
1266-
``` # this should't close the fence!
1267-
a_b = other_thing();
1401+
x_y = thing_do();
1402+
``` # this should't close the fence!
1403+
a_b = other_thing();
12681404
`````<HB>
1269-
&nbsp;&nbsp;&nbsp;&nbsp;And so on.
1405+
And so on.
12701406
");
12711407
}
12721408

@@ -1294,14 +1430,15 @@ mod tests {
12941430
assert_snapshot!(docstring.render_markdown(), @"
12951431
My cool func...<HB>
12961432
<HB>
1297-
Returns:<HB>
1298-
&nbsp;&nbsp;&nbsp;&nbsp;Some details<HB>
1433+
## Returns<HB>
1434+
Some details<HB>
1435+
<HB>
12991436
~~~~~~python
1300-
x_y = thing_do();
1301-
~~~ # this should't close the fence!
1302-
a_b = other_thing();
1437+
x_y = thing_do();
1438+
~~~ # this should't close the fence!
1439+
a_b = other_thing();
13031440
~~~~~~<HB>
1304-
&nbsp;&nbsp;&nbsp;&nbsp;And so on.
1441+
And so on.
13051442
");
13061443
}
13071444

@@ -1672,6 +1809,9 @@ mod tests {
16721809
16731810
Returns:
16741811
str: The return value description
1812+
1813+
Yields:
1814+
int: The next value
16751815
"#;
16761816

16771817
let docstring = Docstring::new(docstring.to_owned());
@@ -1696,19 +1836,25 @@ mod tests {
16961836
16971837
Returns:
16981838
str: The return value description
1839+
1840+
Yields:
1841+
int: The next value
16991842
");
17001843

17011844
assert_snapshot!(docstring.render_markdown(), @"
17021845
This is a function description.<HB>
17031846
<HB>
1704-
Args:<HB>
1705-
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter description<HB>
1706-
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter description<HB>
1707-
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This is a continuation of param2 description.<HB>
1708-
&nbsp;&nbsp;&nbsp;&nbsp;param3: A parameter without type annotation<HB>
1847+
## Parameters<HB>
1848+
`param1` (`str`): The first parameter description<HB>
1849+
`param2` (`int`): The second parameter description<HB>
1850+
&nbsp;&nbsp;&nbsp;&nbsp;This is a continuation of param2 description.<HB>
1851+
`param3`: A parameter without type annotation<HB>
1852+
<HB>
1853+
## Returns<HB>
1854+
`str`: The return value description<HB>
17091855
<HB>
1710-
Returns:<HB>
1711-
&nbsp;&nbsp;&nbsp;&nbsp;str: The return value description
1856+
## Yields<HB>
1857+
`int`: The next value
17121858
");
17131859
}
17141860

@@ -1912,9 +2058,9 @@ mod tests {
19122058
assert_snapshot!(docstring.render_markdown(), @"
19132059
This is a function description.<HB>
19142060
<HB>
1915-
Args:<HB>
1916-
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): Google-style parameter<HB>
1917-
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): Another Google-style parameter<HB>
2061+
## Parameters<HB>
2062+
`param1` (`str`): Google-style parameter<HB>
2063+
`param2` (`int`): Another Google-style parameter<HB>
19182064
<HB>
19192065
Parameters<HB>
19202066
----------<HB>
@@ -2036,8 +2182,8 @@ mod tests {
20362182
assert_snapshot!(docstring.render_markdown(), @"
20372183
This is a function description.<HB>
20382184
<HB>
2039-
Args:<HB>
2040-
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): Google-style parameter<HB>
2185+
## Parameters<HB>
2186+
`param1` (`str`): Google-style parameter<HB>
20412187
<HB>
20422188
## Parameters<HB>
20432189
`param2` (`int`): reST-style parameter<HB>
@@ -2241,9 +2387,9 @@ mod tests {
22412387
assert_snapshot!(docstring_windows.render_markdown(), @"
22422388
This is a function description.<HB>
22432389
<HB>
2244-
Args:<HB>
2245-
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter<HB>
2246-
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter
2390+
## Parameters<HB>
2391+
`param1` (`str`): The first parameter<HB>
2392+
`param2` (`int`): The second parameter
22472393
");
22482394

22492395
assert_snapshot!(docstring_mac.render_plaintext(), @"
@@ -2257,9 +2403,9 @@ mod tests {
22572403
assert_snapshot!(docstring_mac.render_markdown(), @"
22582404
This is a function description.<HB>
22592405
<HB>
2260-
Args:<HB>
2261-
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter<HB>
2262-
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter
2406+
## Parameters<HB>
2407+
`param1` (`str`): The first parameter<HB>
2408+
`param2` (`int`): The second parameter
22632409
");
22642410

22652411
assert_snapshot!(docstring_unix.render_plaintext(), @"
@@ -2273,9 +2419,9 @@ mod tests {
22732419
assert_snapshot!(docstring_unix.render_markdown(), @"
22742420
This is a function description.<HB>
22752421
<HB>
2276-
Args:<HB>
2277-
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter<HB>
2278-
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter
2422+
## Parameters<HB>
2423+
`param1` (`str`): The first parameter<HB>
2424+
`param2` (`int`): The second parameter
22792425
");
22802426
}
22812427

0 commit comments

Comments
 (0)