Skip to content

Commit

Permalink
Use section name range for all section-related docstring diagnostics (a…
Browse files Browse the repository at this point in the history 
…stral-sh#10740)

## Summary

We may not have had access to this in the past, but in short, if the
diagnostic is related to a specific section of a docstring, it seems
better to highlight the section (via the header) than the _entire_
docstring.

This should be completely compatible with existing `# noqa` since it's
always inside of a multi-line string anyway, and in such cases the `#
noqa` is always placed at the end of the multiline string.

Closes astral-sh#10736.
  • Loading branch information
@charliermarsh @Glyphack
charliermarsh authored and Glyphack committed Apr 12, 2024
1 parent 100d129 commit a1adea8
Show file tree
Hide file tree
Showing 17 changed files with 559 additions and 1,009 deletions.
182 changes: 106 additions & 76 deletions crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs
View file

Large diffs are not rendered by default.

56 changes: 20 additions & 36 deletions ...ules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__D214_D214_module.py.snap
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,16 @@
---
source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
---
D214_module.py:1:1: D214 [*] Section is over-indented ("Returns")
|
1 | / """A module docstring with D214 violations
2 | |
3 | | Returns
4 | | -----
5 | | valid returns
6 | |
7 | | Args
8 | | -----
9 | | valid args
10 | | """
| |___^ D214
11 |
12 | import os
|
= help: Remove over-indentation from "Returns"
D214_module.py:3:5: D214 [*] Section is over-indented ("Returns")
|
1 | """A module docstring with D214 violations
2 |
3 | Returns
| ^^^^^^^ D214
4 | -----
5 | valid returns
|
= help: Remove over-indentation from "Returns"

ℹ Safe fix
1 1 | """A module docstring with D214 violations
Expand All @@ -28,23 +21,16 @@ D214_module.py:1:1: D214 [*] Section is over-indented ("Returns")
5 5 | valid returns
6 6 |

D214_module.py:1:1: D214 [*] Section is over-indented ("Args")
|
1 | / """A module docstring with D214 violations
2 | |
3 | | Returns
4 | | -----
5 | | valid returns
6 | |
7 | | Args
8 | | -----
9 | | valid args
10 | | """
| |___^ D214
11 |
12 | import os
|
= help: Remove over-indentation from "Args"
D214_module.py:7:5: D214 [*] Section is over-indented ("Args")
|
5 | valid returns
6 |
7 | Args
| ^^^^ D214
8 | -----
9 | valid args
|
= help: Remove over-indentation from "Args"

ℹ Safe fix
4 4 | -----
Expand All @@ -55,5 +41,3 @@ D214_module.py:1:1: D214 [*] Section is over-indented ("Args")
8 8 | -----
9 9 | valid args
10 10 | """
40 changes: 14 additions & 26 deletions ...c/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__D214_sections.py.snap
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,14 @@
---
source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
---
sections.py:144:5: D214 [*] Section is over-indented ("Returns")
sections.py:146:9: D214 [*] Section is over-indented ("Returns")
|
142 | @expect("D214: Section is over-indented ('Returns')")
143 | def section_overindented(): # noqa: D416
144 | """Toggle the gizmo.
| _____^
145 | |
146 | | Returns
147 | | -------
148 | | A value of some sort.
149 | |
150 | | """
| |_______^ D214
144 | """Toggle the gizmo.
145 |
146 | Returns
| ^^^^^^^ D214
147 | -------
148 | A value of some sort.
|
= help: Remove over-indentation from "Returns"

Expand All @@ -27,18 +22,13 @@ sections.py:144:5: D214 [*] Section is over-indented ("Returns")
148 148 | A value of some sort.
149 149 |

sections.py:558:5: D214 [*] Section is over-indented ("Returns")
sections.py:563:9: D214 [*] Section is over-indented ("Returns")
|
557 | def titlecase_sub_section_header():
558 | """Below, `Returns:` should be considered a section header.
| _____^
559 | |
560 | | Args:
561 | | Here's a note.
562 | |
563 | | Returns:
564 | | """
| |_______^ D214
561 | Here's a note.
562 |
563 | Returns:
| ^^^^^^^ D214
564 | """
|
= help: Remove over-indentation from "Returns"

Expand All @@ -50,6 +40,4 @@ sections.py:558:5: D214 [*] Section is over-indented ("Returns")
563 |+ Returns:
564 564 | """
565 565 |
566 566 |


566 566 |
14 changes: 6 additions & 8 deletions ...r/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__D215_D215.py.snap
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
---
D215.py:1:1: D215 [*] Section underline is over-indented ("TODO")
D215.py:3:5: D215 [*] Section underline is over-indented ("TODO")
|
1 | / """
2 | | TODO:
3 | | -
4 | | """
| |___^ D215
1 | """
2 | TODO:
3 | -
| ^ D215
4 | """
|
= help: Remove over-indentation from "TODO" underline

Expand All @@ -17,5 +17,3 @@ D215.py:1:1: D215 [*] Section underline is over-indented ("TODO")
3 |- -
3 |+
4 4 | """
36 changes: 11 additions & 25 deletions ...c/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__D215_sections.py.snap
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,12 @@
---
source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
---
sections.py:156:5: D215 [*] Section underline is over-indented ("Returns")
sections.py:159:9: D215 [*] Section underline is over-indented ("Returns")
|
154 | @expect("D215: Section underline is over-indented (in section 'Returns')")
155 | def section_underline_overindented(): # noqa: D416
156 | """Toggle the gizmo.
| _____^
157 | |
158 | | Returns
159 | | -------
160 | | A value of some sort.
161 | |
162 | | """
| |_______^ D215
158 | Returns
159 | -------
| ^^^^^^^ D215
160 | A value of some sort.
|
= help: Remove over-indentation from "Returns" underline

Expand All @@ -27,17 +20,12 @@ sections.py:156:5: D215 [*] Section underline is over-indented ("Returns")
161 161 |
162 162 | """
sections.py:170:5: D215 [*] Section underline is over-indented ("Returns")
sections.py:173:9: D215 [*] Section underline is over-indented ("Returns")
|
168 | @expect("D414: Section has no content ('Returns')")
169 | def section_underline_overindented_and_contentless(): # noqa: D416
170 | """Toggle the gizmo.
| _____^
171 | |
172 | | Returns
173 | | -------
174 | | """
| |_______^ D215
172 | Returns
173 | -------
| ^^^^^^^ D215
174 | """
|
= help: Remove over-indentation from "Returns" underline

Expand All @@ -49,6 +37,4 @@ sections.py:170:5: D215 [*] Section underline is over-indented ("Returns")
173 |+ ------
174 174 | """
175 175 |
176 176 |


176 176 |
47 changes: 13 additions & 34 deletions ...c/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__D405_sections.py.snap
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,14 @@
---
source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
---
sections.py:17:5: D405 [*] Section name should be properly capitalized ("returns")
sections.py:19:5: D405 [*] Section name should be properly capitalized ("returns")
|
15 | "('Returns', not 'returns')")
16 | def not_capitalized(): # noqa: D416
17 | """Toggle the gizmo.
| _____^
18 | |
19 | | returns
20 | | -------
21 | | A value of some sort.
22 | |
23 | | """
| |_______^ D405
17 | """Toggle the gizmo.
18 |
19 | returns
| ^^^^^^^ D405
20 | -------
21 | A value of some sort.
|
= help: Capitalize "returns"

Expand All @@ -27,27 +22,13 @@ sections.py:17:5: D405 [*] Section name should be properly capitalized ("returns
21 21 | A value of some sort.
22 22 |

sections.py:216:5: D405 [*] Section name should be properly capitalized ("Short summary")
sections.py:218:5: D405 [*] Section name should be properly capitalized ("Short summary")
|
214 | @expect("D407: Missing dashed underline after section ('Raises')")
215 | def multiple_sections(): # noqa: D416
216 | """Toggle the gizmo.
| _____^
217 | |
218 | | Short summary
219 | | -------------
220 | |
221 | | This is the function's description, which will also specify what it
222 | | returns.
223 | |
224 | | Returns
225 | | ------
226 | | Many many wonderful things.
227 | | Raises:
228 | | My attention.
229 | |
230 | | """
| |_______^ D405
216 | """Toggle the gizmo.
217 |
218 | Short summary
| ^^^^^^^^^^^^^ D405
219 | -------------
|
= help: Capitalize "Short summary"

Expand All @@ -60,5 +41,3 @@ sections.py:216:5: D405 [*] Section name should be properly capitalized ("Short
219 219 | -------------
220 220 |
221 221 | This is the function's description, which will also specify what it


67 changes: 20 additions & 47 deletions ...c/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__D406_sections.py.snap
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,14 @@
---
source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
---
sections.py:30:5: D406 [*] Section name should end with a newline ("Returns")
sections.py:32:5: D406 [*] Section name should end with a newline ("Returns")
|
28 | "('Returns', not 'Returns:')")
29 | def superfluous_suffix(): # noqa: D416
30 | """Toggle the gizmo.
| _____^
31 | |
32 | | Returns:
33 | | -------
34 | | A value of some sort.
35 | |
36 | | """
| |_______^ D406
30 | """Toggle the gizmo.
31 |
32 | Returns:
| ^^^^^^^ D406
33 | -------
34 | A value of some sort.
|
= help: Add newline after "Returns"

Expand All @@ -27,27 +22,13 @@ sections.py:30:5: D406 [*] Section name should end with a newline ("Returns")
34 34 | A value of some sort.
35 35 |

sections.py:216:5: D406 [*] Section name should end with a newline ("Raises")
sections.py:227:5: D406 [*] Section name should end with a newline ("Raises")
|
214 | @expect("D407: Missing dashed underline after section ('Raises')")
215 | def multiple_sections(): # noqa: D416
216 | """Toggle the gizmo.
| _____^
217 | |
218 | | Short summary
219 | | -------------
220 | |
221 | | This is the function's description, which will also specify what it
222 | | returns.
223 | |
224 | | Returns
225 | | ------
226 | | Many many wonderful things.
227 | | Raises:
228 | | My attention.
229 | |
230 | | """
| |_______^ D406
225 | ------
226 | Many many wonderful things.
227 | Raises:
| ^^^^^^ D406
228 | My attention.
|
= help: Add newline after "Raises"

Expand All @@ -61,20 +42,14 @@ sections.py:216:5: D406 [*] Section name should end with a newline ("Raises")
229 229 |
230 230 | """
sections.py:588:5: D406 [*] Section name should end with a newline ("Parameters")
sections.py:590:5: D406 [*] Section name should end with a newline ("Parameters")
|
587 | def test_lowercase_sub_section_header_should_be_valid(parameters: list[str], value: int): # noqa: D213
588 | """Test that lower case subsection header is valid even if it has the same name as section kind.
| _____^
589 | |
590 | | Parameters:
591 | | ----------
592 | | parameters:
593 | | A list of string parameters
594 | | value:
595 | | Some value
596 | | """
| |_______^ D406
588 | """Test that lower case subsection header is valid even if it has the same name as section kind.
589 |
590 | Parameters:
| ^^^^^^^^^^ D406
591 | ----------
592 | parameters:
|
= help: Add newline after "Parameters"

Expand All @@ -87,5 +62,3 @@ sections.py:588:5: D406 [*] Section name should end with a newline ("Parameters"
591 591 | ----------
592 592 | parameters:
593 593 | A list of string parameters


Loading

0 comments on commit a1adea8

Please sign in to comment.