[pydoclint] Fix false positive when Sphinx directives follow Raises section (DOC502) (#20535)

## Summary

Fixes #18959

---------

Co-authored-by: Brent Westbrook <[email protected]>

Author: danparizher

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC502_google.py

@@ -83,6 +83,37 @@ def calculate_speed(distance: float, time: float) -> float:
         raise
 
 
+# DOC502 regression for Sphinx directive after Raises (issue #18959)
+def foo():
+    """First line.
+
+    Raises:
+        ValueError:
+            some text
+
+    .. versionadded:: 0.7.0
+        The ``init_kwargs`` argument.
+    """
+    raise ValueError
+
+
+# DOC502 regression for following section with colons
+def example_with_following_section():
+    """Summary.
+    
+    Returns:
+        str: The resulting expression.
+    
+    Raises:
+        ValueError: If the unit is not valid.
+    
+    Relation to `time_range_lookup`:
+        - Handles the "start of" modifier.
+        - Example: "start of month" → `DATETRUNC()`.
+    """
+    raise ValueError
+
+
 # This should NOT trigger DOC502 because OSError is explicitly re-raised
 def f():
     """Do nothing.

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC502_numpy.py

@@ -117,3 +117,33 @@ def calculate_speed(distance: float, time: float) -> float:
     except TypeError:
         print("Not a number? Shame on you!")
         raise
+
+
+# DOC502 regression for Sphinx directive after Raises (issue #18959)
+def foo():
+    """First line.
+
+    Raises
+    ------
+    ValueError
+        some text
+
+    .. versionadded:: 0.7.0
+        The ``init_kwargs`` argument.
+    """
+    raise ValueError
+
+# Make sure we don't bail out on a Sphinx directive in the description of one
+# of the exceptions
+def foo():
+    """First line.
+
+    Raises
+    ------
+    ValueError
+        some text
+        .. math:: e^{xception}
+    ZeroDivisionError
+        Will not be raised, DOC502
+    """
+    raise ValueError

crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs

@@ -722,12 +722,30 @@ fn parse_raises(content: &str, style: Option<SectionStyle>) -> Vec<QualifiedName
 /// ```
 fn parse_raises_google(content: &str) -> Vec<QualifiedName<'_>> {
     let mut entries: Vec<QualifiedName> = Vec::new();
-    for potential in content.lines() {
-        let Some(colon_idx) = potential.find(':') else {
-            continue;
-        };
-        let entry = potential[..colon_idx].trim();
-        entries.push(QualifiedName::user_defined(entry));
+    let mut lines = content.lines().peekable();
+    let Some(first) = lines.peek() else {
+        return entries;
+    };
+    let indentation = &first[..first.len() - first.trim_start().len()];
+    for potential in lines {
+        if let Some(entry) = potential.strip_prefix(indentation) {
+            if let Some(first_char) = entry.chars().next() {
+                if !first_char.is_whitespace() {
+                    if let Some(colon_idx) = entry.find(':') {
+                        let entry = entry[..colon_idx].trim();
+                        if !entry.is_empty() {
+                            entries.push(QualifiedName::user_defined(entry));
+                        }
+                    }
+                }
+            }
+        } else {
+            // If we can't strip the expected indentation, check if this is a dedented line
+            // (not blank) - if so, break early as we've reached the end of this section
+            if !potential.trim().is_empty() {
+                break;
+            }
+        }
     }
     entries
 }
@@ -751,6 +769,12 @@ fn parse_raises_numpy(content: &str) -> Vec<QualifiedName<'_>> {
     let indentation = &dashes[..dashes.len() - dashes.trim_start().len()];
     for potential in lines {
         if let Some(entry) = potential.strip_prefix(indentation) {
+            // Check for Sphinx directives (lines starting with ..) - these indicate the end of the
+            // section. In numpy-style, exceptions are dedented to the same level as sphinx
+            // directives.
+            if entry.starts_with("..") {
+                break;
+            }
             if let Some(first_char) = entry.chars().next() {
                 if !first_char.is_whitespace() {
                     entries.push(QualifiedName::user_defined(entry.trim_end()));

crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-exception_DOC502_numpy.py.snap

@@ -95,3 +95,23 @@ DOC502 Raised exception is not explicitly raised: `DivisionByZero`
 82 |           return distance / time
    |
 help: Remove `DivisionByZero` from the docstring
+
+DOC502 Raised exception is not explicitly raised: `ZeroDivisionError`
+   --> DOC502_numpy.py:139:5
+    |
+137 |   # of the exceptions
+138 |   def foo():
+139 | /     """First line.
+140 | |
+141 | |     Raises
+142 | |     ------
+143 | |     ValueError
+144 | |         some text
+145 | |         .. math:: e^{xception}
+146 | |     ZeroDivisionError
+147 | |         Will not be raised, DOC502
+148 | |     """
+    | |_______^
+149 |       raise ValueError
+    |
+help: Remove `ZeroDivisionError` from the docstring