pick up docstrings from pyi files, fix #613

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 <!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
 
+ - pdoc now also picks up docstrings from `.pyi` stub files.
  - Fix horizontal scroll navigation z-index issue.
    ([#616](https://github.com/mitmproxy/pdoc/pull/616), @Domi04151309)
 

pdoc/doc_pyi.py

@@ -70,9 +70,12 @@ def _patch_doc(target_doc: doc.Doc, stub_mod: doc.Module) -> None:
     if isinstance(target_doc, doc.Function) and isinstance(stub_doc, doc.Function):
         target_doc.signature = stub_doc.signature
         target_doc.funcdef = stub_doc.funcdef
+        target_doc.docstring = stub_doc.docstring or target_doc.docstring
     elif isinstance(target_doc, doc.Variable) and isinstance(stub_doc, doc.Variable):
         target_doc.annotation = stub_doc.annotation
+        target_doc.docstring = stub_doc.docstring or target_doc.docstring
     elif isinstance(target_doc, doc.Namespace) and isinstance(stub_doc, doc.Namespace):
+        target_doc.docstring = stub_doc.docstring or target_doc.docstring
         for m in target_doc.members.values():
             _patch_doc(m, stub_mod)
     else:

test/testdata/type_stub.html

@@ -142,7 +142,7 @@ <h1 class="modulename">
     </div>
     <a class="headerlink" href="#var"></a>
 
-            <div class="docstring"><p>A simple variable.</p>
+            <div class="docstring"><p>Docstring override from the .pyi file.</p>
 </div>
 
 

test/testdata/type_stub.pyi

@@ -4,6 +4,7 @@ from typing import Iterable
 def func(x: str, y: Any, z: "Iterable[str]") -> int: ...
 
 var: list[str]
+"""Docstring override from the .pyi file."""
 
 class Class:
     attr: int

test/testdata/type_stub.txt

@@ -1,6 +1,6 @@
 <module type_stub  # This module has an a…
     <function def func(x: str, y: Any, z: Iterable[str]) -> int: ...  # A simple function.>
-    <var var: list[str] = []  # A simple variable.>
+    <var var: list[str] = []  # Docstring override f…>
     <class type_stub.Class
         <method def __init__(): ...>
         <var attr: int = 42  # An attribute>