Skip to content

[ty] Render sections in Google-formatted docstrings as Markdown #25784

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lerebear wants to merge 1 commit into
base: lerebear/push-yzwunnvwmmlx
Choose a base branch
from
+1,102 −59
Draft

[ty] Render sections in Google-formatted docstrings as Markdown #25784

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 179 additions & 33 deletions crates/ty_ide/src/docstring.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -865,6 +865,141 @@ mod tests {
"#);
}

#[test]
fn google_sections_render_edge_cases() {
let _snap = bind_docstring_snapshot_filters();
let docstring = Docstring::new(
"\
Attributes:
name (str): Display name.
coords (tuple(int, int)): Coordinate pair.
callback (Callable(int, str)): Converts raw values.
if name:
return name

Raises:
ValueError: If invalid."
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @"
## Attributes<HB>
`name` (`str`): Display name.<HB>
`coords` (`tuple(int, int)`): Coordinate pair.<HB>
`callback` (`Callable(int, str)`): Converts raw values.<HB>
&nbsp;&nbsp;&nbsp;&nbsp;if name:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return name<HB>
<HB>
## Raises<HB>
`ValueError`: If invalid.
");

let docstring = Docstring::new(
"\
Args:
value: Description.
```python
Args:
nested: Still code.
Returns:
Still code.
```
url (Literal[\"http://\"]): URL."
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @r#"
## Parameters<HB>
`value`: Description.<HB>
<HB>
```python
Args:
nested: Still code.
Returns:
Still code.
```<HB>
`url` (`Literal["http://"]`): URL.
"#);

let docstring = Docstring::new(
"\
Summary.

Returns:
Literal[\"http://\"]: First paragraph.

Second paragraph."
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @r#"
Summary.<HB>
<HB>
## Returns<HB>
`Literal["http://"]`: First paragraph.<HB>
&nbsp;&nbsp;&nbsp;&nbsp;<HB>
&nbsp;&nbsp;&nbsp;&nbsp;Second paragraph.
"#);

let docstring = Docstring::new(
"\
Summary.

Args:
value: Description.
>>> value
42"
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @"
Summary.<HB>
<HB>
## Parameters<HB>
`value`: Description.<HB>
```````````python
>>> value
42
```````````
");

let docstring = Docstring::new(
"\
Returns:
https://example.com: more details."
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @"
## Returns<HB>
https://example.com: more details.
");

let docstring = Docstring::new(
"\
Returns:
str:Description without whitespace."
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @"
## Returns<HB>
`str`: Description without whitespace.
");

let docstring = Docstring::new(
"\
Args:
: Missing name."
.to_owned(),
);

assert_snapshot!(docstring.render_markdown(), @"
Args:<HB>
: Missing name.
");
}

// A literal block where the `::` is flush with the paragraph
// and should become `:`
#[test]
Expand Down Expand Up @@ -1259,14 +1394,15 @@ mod tests {
assert_snapshot!(docstring.render_markdown(), @"
My cool func...<HB>
<HB>
Returns:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;Some details<HB>
## Returns<HB>
Some details<HB>
<HB>
`````python
x_y = thing_do();
``` # this should't close the fence!
a_b = other_thing();
x_y = thing_do();
``` # this should't close the fence!
a_b = other_thing();
`````<HB>
&nbsp;&nbsp;&nbsp;&nbsp;And so on.
And so on.
");
}

Expand Down Expand Up @@ -1294,14 +1430,15 @@ mod tests {
assert_snapshot!(docstring.render_markdown(), @"
My cool func...<HB>
<HB>
Returns:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;Some details<HB>
## Returns<HB>
Some details<HB>
<HB>
~~~~~~python
x_y = thing_do();
~~~ # this should't close the fence!
a_b = other_thing();
x_y = thing_do();
~~~ # this should't close the fence!
a_b = other_thing();
~~~~~~<HB>
&nbsp;&nbsp;&nbsp;&nbsp;And so on.
And so on.
");
}

Expand Down Expand Up @@ -1672,6 +1809,9 @@ mod tests {

Returns:
str: The return value description

Yields:
int: The next value
"#;

let docstring = Docstring::new(docstring.to_owned());
Expand All @@ -1696,19 +1836,25 @@ mod tests {

Returns:
str: The return value description

Yields:
int: The next value
");

assert_snapshot!(docstring.render_markdown(), @"
This is a function description.<HB>
<HB>
Args:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter description<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter description<HB>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;This is a continuation of param2 description.<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param3: A parameter without type annotation<HB>
## Parameters<HB>
`param1` (`str`): The first parameter description<HB>
`param2` (`int`): The second parameter description<HB>
&nbsp;&nbsp;&nbsp;&nbsp;This is a continuation of param2 description.<HB>
`param3`: A parameter without type annotation<HB>
<HB>
## Returns<HB>
`str`: The return value description<HB>
<HB>
Returns:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;str: The return value description
## Yields<HB>
`int`: The next value
");
}

Expand Down Expand Up @@ -1912,9 +2058,9 @@ mod tests {
assert_snapshot!(docstring.render_markdown(), @"
This is a function description.<HB>
<HB>
Args:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): Google-style parameter<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): Another Google-style parameter<HB>
## Parameters<HB>
`param1` (`str`): Google-style parameter<HB>
`param2` (`int`): Another Google-style parameter<HB>
<HB>
Parameters<HB>
----------<HB>
Expand Down Expand Up @@ -2036,8 +2182,8 @@ mod tests {
assert_snapshot!(docstring.render_markdown(), @"
This is a function description.<HB>
<HB>
Args:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): Google-style parameter<HB>
## Parameters<HB>
`param1` (`str`): Google-style parameter<HB>
<HB>
## Parameters<HB>
`param2` (`int`): reST-style parameter<HB>
Expand Down Expand Up @@ -2241,9 +2387,9 @@ mod tests {
assert_snapshot!(docstring_windows.render_markdown(), @"
This is a function description.<HB>
<HB>
Args:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter
## Parameters<HB>
`param1` (`str`): The first parameter<HB>
`param2` (`int`): The second parameter
");

assert_snapshot!(docstring_mac.render_plaintext(), @"
Expand All @@ -2257,9 +2403,9 @@ mod tests {
assert_snapshot!(docstring_mac.render_markdown(), @"
This is a function description.<HB>
<HB>
Args:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter
## Parameters<HB>
`param1` (`str`): The first parameter<HB>
`param2` (`int`): The second parameter
");

assert_snapshot!(docstring_unix.render_plaintext(), @"
Expand All @@ -2273,9 +2419,9 @@ mod tests {
assert_snapshot!(docstring_unix.render_markdown(), @"
This is a function description.<HB>
<HB>
Args:<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param1 (str): The first parameter<HB>
&nbsp;&nbsp;&nbsp;&nbsp;param2 (int): The second parameter
## Parameters<HB>
`param1` (`str`): The first parameter<HB>
`param2` (`int`): The second parameter
");
}

Expand Down
Loading
Loading