improve rendering of @overload in pyi files (#652)

.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

CHANGELOG.md

@@ -1,8 +1,11 @@
 # Release History
 
+<!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
+
 ## Unreleased: pdoc next
 
-<!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
+ - 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
 

pdoc/doc_pyi.py

@@ -9,13 +9,16 @@
 import sys
 import traceback
 import types
+import typing
 from unittest import mock
 import warnings
 
 from pdoc import doc
 
 from ._compat import cache
 
+overload_docstr = typing.overload(lambda: None).__doc__
+
 
 @cache
 def find_stub_file(module_name: str) -> Path | None:
@@ -68,6 +71,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

test/testdata/type_stub.html

@@ -53,6 +53,9 @@ <h2>API Documentation</h2>
                         <li>
                                 <a class="function" href="#Class.no_type_annotation">no_type_annotation</a>
                         </li>
+                        <li>
+                                <a class="function" href="#Class.overloaded">overloaded</a>
+                        </li>
                 </ul>
 
             </li>
@@ -108,6 +111,9 @@ <h1 class="modulename">
 </span><span id="L-27"><a href="#L-27"><span class="linenos">27</span></a>
 </span><span id="L-28"><a href="#L-28"><span class="linenos">28</span></a>    <span class="k">def</span> <span class="nf">no_type_annotation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
 </span><span id="L-29"><a href="#L-29"><span class="linenos">29</span></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;A method not present in the .pyi file.&quot;&quot;&quot;</span>
+</span><span id="L-30"><a href="#L-30"><span class="linenos">30</span></a>
+</span><span id="L-31"><a href="#L-31"><span class="linenos">31</span></a>    <span class="k">def</span> <span class="nf">overloaded</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
+</span><span id="L-32"><a href="#L-32"><span class="linenos">32</span></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;An overloaded method.&quot;&quot;&quot;</span>
 </span></pre></div>
 
 
@@ -174,6 +180,9 @@ <h1 class="modulename">
 </span><span id="Class-28"><a href="#Class-28"><span class="linenos">28</span></a>
 </span><span id="Class-29"><a href="#Class-29"><span class="linenos">29</span></a>    <span class="k">def</span> <span class="nf">no_type_annotation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
 </span><span id="Class-30"><a href="#Class-30"><span class="linenos">30</span></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;A method not present in the .pyi file.&quot;&quot;&quot;</span>
+</span><span id="Class-31"><a href="#Class-31"><span class="linenos">31</span></a>
+</span><span id="Class-32"><a href="#Class-32"><span class="linenos">32</span></a>    <span class="k">def</span> <span class="nf">overloaded</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
+</span><span id="Class-33"><a href="#Class-33"><span class="linenos">33</span></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;An overloaded method.&quot;&quot;&quot;</span>
 </span></pre></div>
 
 
@@ -234,6 +243,27 @@ <h1 class="modulename">
 </div>
 
 
+                            </div>
+                            <div id="Class.overloaded" class="classattr">
+                                        <input id="Class.overloaded-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
+<div class="attr function">
+
+        <span class="def">def</span>
+        <span class="name">overloaded</span><span class="signature pdoc-code condensed">(<span class="param"><span class="o">*</span><span class="n">args</span>, </span><span class="param"><span class="o">**</span><span class="n">kwds</span></span><span class="return-annotation">):</span></span>
+
+                <label class="view-source-button" for="Class.overloaded-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#Class.overloaded"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="Class.overloaded-32"><a href="#Class.overloaded-32"><span class="linenos">32</span></a>    <span class="k">def</span> <span class="nf">overloaded</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
+</span><span id="Class.overloaded-33"><a href="#Class.overloaded-33"><span class="linenos">33</span></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;An overloaded method.&quot;&quot;&quot;</span>
+</span></pre></div>
+
+
+            <div class="docstring"><p>An overloaded method.</p>
+</div>
+
+
                             </div>
                 </section>
                 <section id="Class.Subclass">

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."""

test/testdata/type_stub.pyi

@@ -1,5 +1,6 @@
 from typing import Any
 from typing import Iterable
+from typing import overload
 
 def func(x: str, y: Any, z: "Iterable[str]") -> int: ...
 
@@ -15,3 +16,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: ...

test/testdata/type_stub.txt

@@ -11,5 +11,6 @@
             <method def meth(self, y: bool) -> bool: ...  # A simple method.>
         >
         <method def no_type_annotation(self, z): ...  # A method not present…>
+        <method def overloaded(*args, **kwds): ...  # An overloaded method…>
     >
 >