From 8b99723176cd21061e2c6119aa5ce453259c0ff6 Mon Sep 17 00:00:00 2001
From: Maximilian Hils <git@maximilianhils.com>
Date: Wed, 6 Sep 2023 10:12:00 +0200
Subject: [PATCH] pick up docstrings from pyi files, fix #613

---
 CHANGELOG.md                 | 1 +
 pdoc/doc_pyi.py              | 3 +++
 test/testdata/type_stub.html | 2 +-
 test/testdata/type_stub.pyi  | 1 +
 test/testdata/type_stub.txt  | 2 +-
 5 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82e38d83..60f44d20 100644
--- a/CHANGELOG.md
+++ b/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)
 
diff --git a/pdoc/doc_pyi.py b/pdoc/doc_pyi.py
index 5d509ea8..cdd02cfa 100644
--- a/pdoc/doc_pyi.py
+++ b/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:
diff --git a/test/testdata/type_stub.html b/test/testdata/type_stub.html
index f54344c7..b2b41a48 100644
--- a/test/testdata/type_stub.html
+++ b/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>
 
 
diff --git a/test/testdata/type_stub.pyi b/test/testdata/type_stub.pyi
index b15e297b..ab97e579 100644
--- a/test/testdata/type_stub.pyi
+++ b/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
diff --git a/test/testdata/type_stub.txt b/test/testdata/type_stub.txt
index c98be431..fbbc3ad0 100644
--- a/test/testdata/type_stub.txt
+++ b/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>