From b58fa38681ad50a4fb739a25704f639369e0e5a0 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Tue, 19 Dec 2023 15:52:54 +0100 Subject: [PATCH 1/4] improve rendering of @overload in pyi files --- CHANGELOG.md | 4 +++- pdoc/doc_pyi.py | 7 +++++++ test/testdata/type_stub.html | 30 ++++++++++++++++++++++++++++++ test/testdata/type_stub.py | 3 +++ test/testdata/type_stub.pyi | 7 +++++++ test/testdata/type_stub.txt | 1 + 6 files changed, 51 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d41629f..95b69074 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,10 @@ # Release History + + ## Unreleased: pdoc next - + - Improve rendering of `.pyi` type stubs containing `@typing.overload`. ## 2023-12-13: pdoc 14.2.0 diff --git a/pdoc/doc_pyi.py b/pdoc/doc_pyi.py index cdd02cfa..856e7c89 100644 --- a/pdoc/doc_pyi.py +++ b/pdoc/doc_pyi.py @@ -5,6 +5,7 @@ """ from __future__ import annotations +import typing from pathlib import Path import sys import traceback @@ -16,6 +17,7 @@ from ._compat import cache +overload_docstr = typing.overload(lambda: None).__doc__ @cache def find_stub_file(module_name: str) -> Path | None: @@ -68,6 +70,11 @@ def _patch_doc(target_doc: doc.Doc, stub_mod: doc.Module) -> None: stub_doc = stub_mod if isinstance(target_doc, doc.Function) and isinstance(stub_doc, doc.Function): + # pyi files have functions where all defs have @overload. + # We don't want to pick up the docstring from the typing helper. + if stub_doc.docstring == overload_docstr: + stub_doc.docstring = "" + target_doc.signature = stub_doc.signature target_doc.funcdef = stub_doc.funcdef target_doc.docstring = stub_doc.docstring or target_doc.docstring diff --git a/test/testdata/type_stub.html b/test/testdata/type_stub.html index b2b41a48..6944581d 100644 --- a/test/testdata/type_stub.html +++ b/test/testdata/type_stub.html @@ -53,6 +53,9 @@

API Documentation

  • no_type_annotation
    • +
  • + overloaded +
    • @@ -108,6 +111,9 @@

    27 28 def no_type_annotation(self, z): 29 """A method not present in the .pyi file.""" +30 +31 def overloaded(self, x): +32 """An overloaded method.""" @@ -174,6 +180,9 @@

    28 29 def no_type_annotation(self, z): 30 """A method not present in the .pyi file.""" +31 +32 def overloaded(self, x): +33 """An overloaded method.""" @@ -234,6 +243,27 @@

    + +
    + +
    + + def + overloaded(*args, **kwds): + + + +
    + + 
    32    def overloaded(self, x):
+33        """An overloaded method."""
+
    + + +

    An overloaded method.

    +
    + +
    diff --git a/test/testdata/type_stub.py b/test/testdata/type_stub.py index f668b3a7..e9492dba 100644 --- a/test/testdata/type_stub.py +++ b/test/testdata/type_stub.py @@ -27,3 +27,6 @@ def meth(self, y): def no_type_annotation(self, z): """A method not present in the .pyi file.""" + + def overloaded(self, x): + """An overloaded method.""" diff --git a/test/testdata/type_stub.pyi b/test/testdata/type_stub.pyi index ab97e579..5c0f2dba 100644 --- a/test/testdata/type_stub.pyi +++ b/test/testdata/type_stub.pyi @@ -1,5 +1,7 @@ from typing import Any from typing import Iterable +from typing import overload + def func(x: str, y: Any, z: "Iterable[str]") -> int: ... @@ -15,3 +17,8 @@ class Class: attr: str def meth(self, y: bool) -> bool: ... + + @overload + def overloaded(self, x: int) -> int: ... + @overload + def overloaded(self, x: str) -> str: ... diff --git a/test/testdata/type_stub.txt b/test/testdata/type_stub.txt index fbbc3ad0..7632d43f 100644 --- a/test/testdata/type_stub.txt +++ b/test/testdata/type_stub.txt @@ -11,5 +11,6 @@ bool: ... # A simple method.> > + > > \ No newline at end of file From 837a45c517d726a5b2d2d4dc731913ee786fb1e6 Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Tue, 19 Dec 2023 14:54:00 +0000 Subject: [PATCH 2/4] [autofix.ci] apply automated fixes --- CHANGELOG.md | 1 + pdoc/doc_pyi.py | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 95b69074..d7eca99d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ ## Unreleased: pdoc next - Improve rendering of `.pyi` type stubs containing `@typing.overload`. + ([#652](https://github.com/mitmproxy/pdoc/pull/652), @mhils) ## 2023-12-13: pdoc 14.2.0 diff --git a/pdoc/doc_pyi.py b/pdoc/doc_pyi.py index 856e7c89..f6d465a5 100644 --- a/pdoc/doc_pyi.py +++ b/pdoc/doc_pyi.py @@ -5,11 +5,11 @@ """ from __future__ import annotations -import typing from pathlib import Path import sys import traceback import types +import typing from unittest import mock import warnings @@ -19,6 +19,7 @@ overload_docstr = typing.overload(lambda: None).__doc__ + @cache def find_stub_file(module_name: str) -> Path | None: """Try to find a .pyi file with type stubs for the given module name.""" From e8fc8b8acb3e0569691d99264fa7f8e70a7607f8 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Tue, 19 Dec 2023 15:57:12 +0100 Subject: [PATCH 3/4] fix autofixer --- .github/workflows/autofix.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml index 719e1860..f0e36f58 100644 --- a/.github/workflows/autofix.yml +++ b/.github/workflows/autofix.yml @@ -24,7 +24,6 @@ jobs: - run: ruff --fix-only . - run: ruff format . - - run: git checkout test/testdata/ pdoc/markdown2/ - run: test/test_snapshot.py - uses: mhils/add-pr-ref-in-changelog@main From 8a1d854fe4c08cc41b14b59b7bc1d05ef054f3d9 Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Tue, 19 Dec 2023 14:58:02 +0000 Subject: [PATCH 4/4] [autofix.ci] apply automated fixes --- test/testdata/type_stub.pyi | 1 - 1 file changed, 1 deletion(-) diff --git a/test/testdata/type_stub.pyi b/test/testdata/type_stub.pyi index 5c0f2dba..fc0f403a 100644 --- a/test/testdata/type_stub.pyi +++ b/test/testdata/type_stub.pyi @@ -2,7 +2,6 @@ from typing import Any from typing import Iterable from typing import overload - def func(x: str, y: Any, z: "Iterable[str]") -> int: ... var: list[str]