From 822065a03236c1be2d8897d88bdb0ad56217c467 Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Thu, 20 Jun 2024 22:07:37 -0500 Subject: [PATCH 1/5] wip --- src/sphinx_autodoc_typehints/__init__.py | 8 +- tests/test_integration_issue_384.py | 109 +++++++++++++++++++++++ 2 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 tests/test_integration_issue_384.py diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 0c02ad9..aaa490d 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -740,6 +740,12 @@ def _inject_signature( # noqa: C901 insert_index = len(lines) if insert_index is not None: + + # advance index to the end of paragraph + # nlines = len(lines) + # while insert_index < nlines and (lines[insert_index + 1] == "" or lines[insert_index + 1].startswith(" ")): + # insert_index += 1 + if annotation is None: type_annotation = f":type {arg_name}: " else: @@ -754,7 +760,7 @@ def _inject_signature( # noqa: C901 else: # add to last param doc line type_annotation += formatted_default - lines.insert(insert_index, type_annotation) + lines.insert(insert_index + 1, type_annotation) @dataclass diff --git a/tests/test_integration_issue_384.py b/tests/test_integration_issue_384.py new file mode 100644 index 0000000..8eb571f --- /dev/null +++ b/tests/test_integration_issue_384.py @@ -0,0 +1,109 @@ +from __future__ import annotations + +import re +import sys +from pathlib import Path +from textwrap import dedent, indent +from typing import TYPE_CHECKING, Any, Callable, Literal, NewType, TypeVar # no type comments + +import pytest + +if TYPE_CHECKING: + from io import StringIO + + from sphinx.testing.util import SphinxTestApp + +T = TypeVar("T") +W = NewType("W", str) + + +def expected(expected: str, **options: dict[str, Any]) -> Callable[[T], T]: + def dec(val: T) -> T: + val.EXPECTED = expected + val.OPTIONS = options + return val + + return dec + + +def warns(pattern: str) -> Callable[[T], T]: + def dec(val: T) -> T: + val.WARNING = pattern + return val + + return dec + + +@expected( + """\ +mod.function(x=5) + + Function docstring. + + Parameters: + **x** ("int") -- optional specifier for how to handle complex + data types. See "ivy.func_wrapper.handle_complex_input" for more + detail. + + Returns: + something + + Return type: + bytes +""", +) +def function(x: int = 5, y: int = 10, z: int = 5) -> str: # noqa: ARG001 + """ + Function docstring. + + :param x: optional specifier for how to handle complex data types. See + ``ivy.func_wrapper.handle_complex_input`` for more detail. + :param y: another optional specifier for how to handle complex data types. See + ``ivy.func_wrapper.handle_complex_input`` for more detail. + + :param y: yet another optional specifier for how to handle complex data types. See + ``ivy.func_wrapper.handle_complex_input`` for more detail. + :return: something + :rtype: bytes + """ + + +# Config settings for each test run. +# Config Name: Sphinx Options as Dict. +configs = {"default_conf": {"typehints_defaults": "braces-after"}} + + +@pytest.mark.parametrize("val", [x for x in globals().values() if hasattr(x, "EXPECTED")]) +@pytest.mark.parametrize("conf_run", list(configs.keys())) +@pytest.mark.sphinx("text", testroot="integration") +def test_integration( + app: SphinxTestApp, status: StringIO, warning: StringIO, monkeypatch: pytest.MonkeyPatch, val: Any, conf_run: str +) -> None: + template = ".. autofunction:: mod.{}" + + (Path(app.srcdir) / "index.rst").write_text(template.format(val.__name__)) + app.config.__dict__.update(configs[conf_run]) + app.config.__dict__.update(val.OPTIONS) + monkeypatch.setitem(sys.modules, "mod", sys.modules[__name__]) + app.build() + assert "build succeeded" in status.getvalue() # Build succeeded + + regexp = getattr(val, "WARNING", None) + value = warning.getvalue().strip() + if regexp: + msg = f"Regex pattern did not match.\n Regex: {regexp!r}\n Input: {value!r}" + assert re.search(regexp, value), msg + else: + assert not value + + result = (Path(app.srcdir) / "_build/text/index.txt").read_text() + + expected = val.EXPECTED + if sys.version_info < (3, 10): + expected = expected.replace("NewType", "NewType()") + try: + assert result.strip() == dedent(expected).strip() + except Exception: + indented = indent(f'"""\n{result}\n"""', " " * 4) + print(f"@expected(\n{indented}\n)\n") # noqa: T201 + raise From c0c174b20c9740fa7af1eff8cac483b57fb0c7a7 Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Fri, 21 Jun 2024 19:46:51 -0500 Subject: [PATCH 2/5] wip: unexpected unindent error --- src/sphinx_autodoc_typehints/__init__.py | 17 +++++++----- tests/test_integration_issue_384.py | 33 ++++++++++++++++++++++-- 2 files changed, 41 insertions(+), 9 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index aaa490d..6e68ee0 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -741,11 +741,6 @@ def _inject_signature( # noqa: C901 if insert_index is not None: - # advance index to the end of paragraph - # nlines = len(lines) - # while insert_index < nlines and (lines[insert_index + 1] == "" or lines[insert_index + 1].startswith(" ")): - # insert_index += 1 - if annotation is None: type_annotation = f":type {arg_name}: " else: @@ -756,11 +751,19 @@ def _inject_signature( # noqa: C901 formatted_default = format_default(app, default, annotation is not None) if formatted_default: if app.config.typehints_defaults.endswith("after"): - lines[insert_index] += formatted_default + + # advance index to the end of the :param: paragraph + nlines = len(lines) + i = insert_index + while i < nlines and (lines[i + 1] == "" or lines[i + 1].startswith(" ")): + i = i + 1 + + lines[i] += formatted_default + else: # add to last param doc line type_annotation += formatted_default - lines.insert(insert_index + 1, type_annotation) + lines.insert(insert_index, type_annotation) @dataclass diff --git a/tests/test_integration_issue_384.py b/tests/test_integration_issue_384.py index 8eb571f..83acef9 100644 --- a/tests/test_integration_issue_384.py +++ b/tests/test_integration_issue_384.py @@ -52,7 +52,7 @@ def dec(val: T) -> T: bytes """, ) -def function(x: int = 5, y: int = 10, z: int = 5) -> str: # noqa: ARG001 +def function1(x: int, y: int, z: int) -> str: # noqa: ARG001 """ Function docstring. @@ -61,12 +61,41 @@ def function(x: int = 5, y: int = 10, z: int = 5) -> str: # noqa: ARG001 :param y: another optional specifier for how to handle complex data types. See ``ivy.func_wrapper.handle_complex_input`` for more detail. - :param y: yet another optional specifier for how to handle complex data types. See + :param z: yet another optional specifier for how to handle complex data types. See ``ivy.func_wrapper.handle_complex_input`` for more detail. :return: something :rtype: bytes """ +@expected( + """\ +mod.function(x=5) + + Function docstring. + + Parameters: + **x** ("int") -- optional specifier for how to handle complex + data types. See "ivy.func_wrapper.handle_complex_input" for more + detail. + + Returns: + something + + Return type: + bytes +""", +) +def function(x: int = 5, y: int = 10, z: int = 5) -> str: # noqa: ARG001 + """ + Function docstring. + + :param x: optional specifier + line 2 + + :return: something + :rtype: bytes + """ + # Config settings for each test run. # Config Name: Sphinx Options as Dict. From 2085f69c5e2cd14216b6f73041314e4db7840bda Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Fri, 21 Jun 2024 21:17:22 -0500 Subject: [PATCH 3/5] conforming to pre-commit --- src/sphinx_autodoc_typehints/__init__.py | 33 ++++++++++----- tests/test_integration_issue_384.py | 53 ++++++++---------------- 2 files changed, 39 insertions(+), 47 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 6e68ee0..3eb0764 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -750,20 +750,31 @@ def _inject_signature( # noqa: C901 if app.config.typehints_defaults: formatted_default = format_default(app, default, annotation is not None) if formatted_default: - if app.config.typehints_defaults.endswith("after"): + type_annotation = _append_default(app, lines, insert_index, type_annotation, formatted_default) - # advance index to the end of the :param: paragraph - nlines = len(lines) - i = insert_index - while i < nlines and (lines[i + 1] == "" or lines[i + 1].startswith(" ")): - i = i + 1 - - lines[i] += formatted_default + lines.insert(insert_index, type_annotation) - else: # add to last param doc line - type_annotation += formatted_default - lines.insert(insert_index, type_annotation) +def _append_default( + app: Sphinx, lines: list[str], insert_index: int, type_annotation: str, formatted_default: str +) -> str: + if app.config.typehints_defaults.endswith("after"): + # advance the index to the end of the :param: paragraphs + # (terminated by a line with no indentation) + # append default to the last nonempty line + nlines = len(lines) + i = insert_index + 1 + j = insert_index # last nonempty line + while i < nlines and (not lines[i] or lines[i].startswith(" ")): + if lines[i]: + j = i + i += 1 + lines[j] += formatted_default + + else: # add to last param doc line + type_annotation += formatted_default + + return type_annotation @dataclass diff --git a/tests/test_integration_issue_384.py b/tests/test_integration_issue_384.py index 83acef9..66815e6 100644 --- a/tests/test_integration_issue_384.py +++ b/tests/test_integration_issue_384.py @@ -4,7 +4,7 @@ import sys from pathlib import Path from textwrap import dedent, indent -from typing import TYPE_CHECKING, Any, Callable, Literal, NewType, TypeVar # no type comments +from typing import TYPE_CHECKING, Any, Callable, NewType, TypeVar # no type comments import pytest @@ -36,61 +36,42 @@ def dec(val: T) -> T: @expected( """\ -mod.function(x=5) +mod.function(x=5, y=10, z=15) Function docstring. Parameters: - **x** ("int") -- optional specifier for how to handle complex - data types. See "ivy.func_wrapper.handle_complex_input" for more - detail. - - Returns: - something + * **x** ("int") -- optional specifier line 2 (default: "5") - Return type: - bytes -""", -) -def function1(x: int, y: int, z: int) -> str: # noqa: ARG001 - """ - Function docstring. + * **y** ("int") -- - :param x: optional specifier for how to handle complex data types. See - ``ivy.func_wrapper.handle_complex_input`` for more detail. - :param y: another optional specifier for how to handle complex data types. See - ``ivy.func_wrapper.handle_complex_input`` for more detail. + another optional line 4 - :param z: yet another optional specifier for how to handle complex data types. See - ``ivy.func_wrapper.handle_complex_input`` for more detail. - :return: something - :rtype: bytes - """ + second paragraph for y (default: "10") -@expected( - """\ -mod.function(x=5) - - Function docstring. + * **z** ("int") -- yet another optional s line 6 (default: "15") - Parameters: - **x** ("int") -- optional specifier for how to handle complex - data types. See "ivy.func_wrapper.handle_complex_input" for more - detail. - Returns: something Return type: bytes + """, ) -def function(x: int = 5, y: int = 10, z: int = 5) -> str: # noqa: ARG001 +def function(x: int = 5, y: int = 10, z: int = 15) -> str: # noqa: ARG001 """ Function docstring. - :param x: optional specifier + :param x: optional specifier line 2 + :param y: another optional + line 4 + + second paragraph for y + + :param z: yet another optional s + line 6 :return: something :rtype: bytes From a071d8b06055f6f73249dd55057d58abd7e6a4cd Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 22 Jun 2024 02:17:40 +0000 Subject: [PATCH 4/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- src/sphinx_autodoc_typehints/__init__.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 3eb0764..050136b 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -709,7 +709,7 @@ def _inject_types_to_docstring( # noqa: PLR0913, PLR0917 _inject_rtype(type_hints, original_obj, app, what, name, lines) -def _inject_signature( # noqa: C901 +def _inject_signature( type_hints: dict[str, Any], signature: inspect.Signature, app: Sphinx, @@ -740,7 +740,6 @@ def _inject_signature( # noqa: C901 insert_index = len(lines) if insert_index is not None: - if annotation is None: type_annotation = f":type {arg_name}: " else: From 75197566ced9a3a309661b1f0c0d76a6418a1c1e Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Fri, 21 Jun 2024 21:40:55 -0500 Subject: [PATCH 5/5] use descriptive index variable names --- src/sphinx_autodoc_typehints/__init__.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 050136b..efa2a21 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -762,13 +762,13 @@ def _append_default( # (terminated by a line with no indentation) # append default to the last nonempty line nlines = len(lines) - i = insert_index + 1 - j = insert_index # last nonempty line - while i < nlines and (not lines[i] or lines[i].startswith(" ")): - if lines[i]: - j = i - i += 1 - lines[j] += formatted_default + next_index = insert_index + 1 + append_index = insert_index # last nonempty line + while next_index < nlines and (not lines[next_index] or lines[next_index].startswith(" ")): + if lines[next_index]: + append_index = next_index + next_index += 1 + lines[append_index] += formatted_default else: # add to last param doc line type_annotation += formatted_default