From bdeb495ce68ba4730cc4561c31a27f78e7d1522b Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Fri, 20 Jan 2023 09:17:50 -0800 Subject: [PATCH 1/4] Disable GoogleDocstring._lookup_annotation This function never does the correct thing and even if it did the correct thing it would be a problem for us because the redered type annotation isn't processed by sphinx-autodoc-typehints. Resolves issue 308 --- src/sphinx_autodoc_typehints/__init__.py | 9 ++++++ tests/test_integration.py | 39 ++++++++++++++++++++++-- 2 files changed, 45 insertions(+), 3 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index c87d0d27..32c6e8d7 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -19,6 +19,7 @@ from sphinx.environment import BuildEnvironment from sphinx.ext.autodoc import Options from sphinx.ext.autodoc.mock import mock +from sphinx.ext.napoleon.docstring import GoogleDocstring from sphinx.util import logging from sphinx.util.inspect import signature as sphinx_signature from sphinx.util.inspect import stringify_signature @@ -808,6 +809,13 @@ def fix_autodoc_typehints_for_overloaded_methods() -> None: del MethodDocumenter.format_signature +def patched_lookup_annotation(*_args) -> str: # noqa: U101 + """GoogleDocstring._lookup_annotation sometimes adds incorrect type + annotations to constructor parameters (and otherwise does nothing). Disable + it so we can handle this on our own. + """ + return "" + def setup(app: Sphinx) -> dict[str, bool]: app.add_config_value("always_document_param_types", False, "html") app.add_config_value("typehints_fully_qualified", False, "env") @@ -823,6 +831,7 @@ def setup(app: Sphinx) -> dict[str, bool]: app.connect("autodoc-process-docstring", process_docstring) fix_autodoc_typehints_for_overloaded_methods() patch_attribute_handling(app) + GoogleDocstring._lookup_annotation = patched_lookup_annotation return {"parallel_read_safe": True} diff --git a/tests/test_integration.py b/tests/test_integration.py index 2907dbf8..b1d614ea 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -5,8 +5,8 @@ from io import StringIO from mailbox import Mailbox from pathlib import Path -from textwrap import dedent -from types import CodeType +from textwrap import dedent, indent +from types import CodeType, ModuleType from typing import Any, Callable, Optional, TypeVar, Union, overload import pytest @@ -909,6 +909,38 @@ def decorator_2(f: Any) -> Any: f +@expected( + """ + class mod.ParamAndAttributeHaveSameName(blah) + + A Class + + Parameters: + **blah** ("CodeType") -- Description of parameter blah + + blah: "ModuleType" + + Description of attribute blah + + """ +) +class ParamAndAttributeHaveSameName: + """ + A Class + + Parameters + ---------- + blah: + Description of parameter blah + """ + + def __init__(self, blah: CodeType): # noqa: U100 + pass + + blah: ModuleType + """Description of attribute blah""" + + AUTO_FUNCTION = ".. autofunction:: mod.{}" AUTO_CLASS = """\ .. autoclass:: mod.{} @@ -949,5 +981,6 @@ def test_integration(app: SphinxTestApp, status: StringIO, warning: StringIO, mo try: assert result.strip() == dedent(expected).strip() except Exception: - print(f"Result was:\n{result}\n\n") + indented = indent(f'"""\n{result}\n"""', " " * 4) + print(f"@expected(\n{indented}\n)\n") raise From 6dae121ef49151d118c7db8d63aaea23c4ba3936 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 20 Jan 2023 17:20:54 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- src/sphinx_autodoc_typehints/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 32c6e8d7..b3ca84db 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -816,6 +816,7 @@ def patched_lookup_annotation(*_args) -> str: # noqa: U101 """ return "" + def setup(app: Sphinx) -> dict[str, bool]: app.add_config_value("always_document_param_types", False, "html") app.add_config_value("typehints_fully_qualified", False, "env") From 8f14698cf8057f21366dbeba2eaffd3921e6613e Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Fri, 20 Jan 2023 09:25:25 -0800 Subject: [PATCH 3/4] Minor fixes --- src/sphinx_autodoc_typehints/__init__.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 32c6e8d7..74eb0e20 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -816,6 +816,11 @@ def patched_lookup_annotation(*_args) -> str: # noqa: U101 """ return "" + +def patch_google_docstring_lookup_annotation(): + GoogleDocstring._lookup_annotation = patched_lookup_annotation # type: ignore[assignment] + + def setup(app: Sphinx) -> dict[str, bool]: app.add_config_value("always_document_param_types", False, "html") app.add_config_value("typehints_fully_qualified", False, "env") @@ -831,7 +836,7 @@ def setup(app: Sphinx) -> dict[str, bool]: app.connect("autodoc-process-docstring", process_docstring) fix_autodoc_typehints_for_overloaded_methods() patch_attribute_handling(app) - GoogleDocstring._lookup_annotation = patched_lookup_annotation + patch_google_docstring_lookup_annotation() return {"parallel_read_safe": True} From 18a5e71b57255ebc8a9d32d91d3a707e9bc05778 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Fri, 20 Jan 2023 09:25:45 -0800 Subject: [PATCH 4/4] Minor fixes --- src/sphinx_autodoc_typehints/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 74eb0e20..9185819f 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -809,7 +809,7 @@ def fix_autodoc_typehints_for_overloaded_methods() -> None: del MethodDocumenter.format_signature -def patched_lookup_annotation(*_args) -> str: # noqa: U101 +def patched_lookup_annotation(*_args: Any) -> str: # noqa: U101 """GoogleDocstring._lookup_annotation sometimes adds incorrect type annotations to constructor parameters (and otherwise does nothing). Disable it so we can handle this on our own. @@ -817,7 +817,7 @@ def patched_lookup_annotation(*_args) -> str: # noqa: U101 return "" -def patch_google_docstring_lookup_annotation(): +def patch_google_docstring_lookup_annotation() -> None: GoogleDocstring._lookup_annotation = patched_lookup_annotation # type: ignore[assignment]