Verbose error in fix mode for utils/check_docstrings.py (#38915)

* fix ast deprecations for python 3.14: replace node.n by node.value and use `ast.Constant`

More verbose exceptions in `fix_docstring` on docstring formatting issues.

utils/check_docstrings.py

@@ -681,8 +681,8 @@ def eval_math_expression(expression: str) -> Optional[Union[float, int]]:
 
 
 def eval_node(node):
-    if isinstance(node, ast.Num):  # <number>
+    if isinstance(node, ast.Constant) and type(node.value) in (int, float, complex):
-        return node.n
+        return node.value
     elif isinstance(node, ast.BinOp):  # <left> <operator> <right>
         return MATH_OPERATORS[type(node.op)](eval_node(node.left), eval_node(node.right))
     elif isinstance(node, ast.UnaryOp):  # <operator> <operand> e.g., -1
@@ -941,7 +941,8 @@ def fix_docstring(obj: Any, old_doc_args: str, new_doc_args: str):
         idx += 1
 
     if idx == len(source):
-        # Args are not defined in the docstring of this object
+        # Args are not defined in the docstring of this object. This can happen when the docstring is inherited.
+        # In this case, we are not trying to fix it on the child object.
         return
 
     # Get to the line where we stop documenting arguments
@@ -958,7 +959,21 @@ def fix_docstring(obj: Any, old_doc_args: str, new_doc_args: str):
 
     if "".join(source[start_idx:idx])[:-1] != old_doc_args:
         # Args are not fully defined in the docstring of this object
-        return
+        # This can happen due to a mismatch in indentation calculation where the docstring parsing
+        # in match_docstring_with_signature uses obj.__doc__.split("\n") while here we use
+        # inspect.getsourcelines(obj) which can have different line endings or indentation.
+        # See https://github.com/huggingface/transformers/pull/38915/files#r2200675302 for more details.
+        obj_file = find_source_file(obj)
+        actual_args_section = "".join(source[start_idx:idx])[:-1]
+        raise ValueError(
+            f"Cannot fix docstring of {obj.__name__} in {obj_file} because the argument section in the source code "
+            f"does not match the expected format. This usually happens when:\n"
+            f"1. The argument section is not properly indented\n"
+            f"2. The argument section contains unexpected formatting\n"
+            f"3. The docstring parsing failed to correctly identify the argument boundaries\n\n"
+            f"Expected argument section:\n{repr(old_doc_args)}\n\n"
+            f"Actual argument section found:\n{repr(actual_args_section)}\n\n"
+        )
 
     obj_file = find_source_file(obj)
     with open(obj_file, "r", encoding="utf-8") as f: