🐛 fix(docstring): keep types on params with a trailing underscore (#714)

Author: gaborbernat

src/sphinx_autodoc_typehints/__init__.py

@@ -325,9 +325,9 @@ def _inject_arg_signature(  # noqa: PLR0913, PLR0917
     doc_description = _extract_doc_description(annotation) if annotation is not None else None
 
     if arg_name.endswith("_"):
-        arg_name = f"{arg_name[:-1]}\\_"
-
-    insert_index = fmt.find_param(lines, arg_name)
+        arg_name, insert_index = _find_trailing_underscore_param(lines, arg_name, fmt)
+    else:
+        insert_index = fmt.find_param(lines, arg_name)
 
     if (
         insert_index is not None
@@ -376,6 +376,21 @@ def _inject_arg_signature(  # noqa: PLR0913, PLR0917
     lines.insert(insert_index, type_annotation)
 
 
+def _find_trailing_underscore_param(lines: list[str], arg_name: str, fmt: Any) -> tuple[str, int | None]:
+    escaped_name = f"{arg_name[:-1]}\\_"
+    if (insert_index := fmt.find_param(lines, escaped_name)) is not None:
+        return escaped_name, insert_index
+    if (insert_index := fmt.find_param(lines, arg_name)) is None:
+        return escaped_name, None
+    # napoleon only escapes the trailing underscore when strip_signature_backslash is on, and docutils
+    # swallows an unescaped one as reference markup — see issue #708
+    rewritten = lines[insert_index].replace(f" {arg_name}:", f" {escaped_name}:", 1)
+    if rewritten == lines[insert_index]:
+        return arg_name, insert_index
+    lines[insert_index] = rewritten
+    return escaped_name, insert_index
+
+
 def _remove_preexisting_type(lines: list[str], preexisting_line: str) -> int:
     idx = lines.index(preexisting_line)
     end = idx + 1

tests/test_init.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import inspect
+from typing import Any
 from unittest.mock import MagicMock, create_autospec, patch
 
+import pytest
 from conftest import make_docstring_app, make_sig_app
 from sphinx.application import Sphinx
 from sphinx.config import Config
@@ -309,6 +311,52 @@ def func(fp: int) -> None: ...
     assert "int" in type_lines[0]
 
 
+def _trailing_underscore_func(lambda_: float) -> None: ...
+
+
+def _trailing_underscore_starred_func(*args_: float) -> None: ...
+
+
+def _trailing_underscore_undocumented_func(x_: float) -> None: ...
+
+
+@pytest.mark.parametrize(
+    ("func", "lines", "expected_param_line", "expected_type_name"),
+    [
+        pytest.param(
+            _trailing_underscore_func,
+            [":param lambda_: description"],
+            ":param lambda\\_: description",
+            "lambda\\_",
+            id="unescaped-line-rewritten",
+        ),
+        pytest.param(
+            _trailing_underscore_starred_func,
+            [":param \\*args_: description"],
+            ":param \\*args_: description",
+            "args_",
+            id="starred-line-kept",
+        ),
+        pytest.param(
+            _trailing_underscore_undocumented_func,
+            [],
+            ":param x\\_:",
+            "x\\_",
+            id="undocumented-escaped",
+        ),
+    ],
+)
+def test_process_docstring_trailing_underscore_param(
+    func: Any, lines: list[str], expected_param_line: str, expected_type_name: str
+) -> None:
+    """napoleon emits ``:param lambda_:`` unescaped by default; the param line must be rewritten to
+    the escaped form and the type attached, except for forms that cannot be rewritten (issue #708)."""
+    app = make_docstring_app(typehints_document_rtype=False, always_document_param_types=True)
+    process_docstring(app, "function", "test.func", func, None, lines)
+    assert expected_param_line in lines
+    assert any(line.startswith(":type ") and expected_type_name in line and "float" in line for line in lines)
+
+
 def test_process_signature_annotations_name_error() -> None:
     """PEP 649 lazy annotations raising NameError must not propagate from process_signature."""
 

tests/test_integration.py

@@ -304,6 +304,61 @@ def function(x: bool, y: int, z_: Optional[str] = None) -> str:
     """
 
 
+@expected(
+    """\
+mod.function_with_trailing_underscore_numpy(a, lambda_=None)
+
+   Do nothing.
+
+   Parameters:
+      * **a** ("int") -- Description for a.
+
+      * **lambda_** ("float" | "None", default: "None") -- Description
+        for lambda.
+
+   Return type:
+      "None"
+""",
+    typehints_defaults="comma",
+)
+def function_with_trailing_underscore_numpy(a: int, lambda_: float | None = None) -> None:
+    """Do nothing.
+
+    Parameters
+    ----------
+    a
+        Description for a.
+    lambda_
+        Description for lambda.
+    """
+
+
+@expected(
+    """\
+mod.function_with_trailing_underscore_google(a, lambda_=None)
+
+   Do nothing.
+
+   Parameters:
+      * **a** ("int") -- Description for a.
+
+      * **lambda_** ("float" | "None", default: "None") -- Description
+        for lambda.
+
+   Return type:
+      "None"
+""",
+    typehints_defaults="comma",
+)
+def function_with_trailing_underscore_google(a: int, lambda_: float | None = None) -> None:
+    """Do nothing.
+
+    Args:
+        a: Description for a.
+        lambda_: Description for lambda.
+    """
+
+
 @expected(
     """\
 mod.function_with_starred_documentation_param_names(*args, **kwargs)