fix numpydoc processing

fix #758

Author: mhils

CHANGELOG.md

@@ -4,7 +4,11 @@
 
 ## Unreleased: pdoc next
 
-- Fix handling of URL-escaped module names ([#787](https://github.com/mitmproxy/pdoc/pull/787), @iFreilicht)
+- Fix a bug where invalid Numpydoc docstrings would raise an exception.
+- Improve debuggability of docstring processing
+  ([#784](https://github.com/mitmproxy/pdoc/pull/784), @tobiscode)
+- Fix handling of URL-escaped module names
+  ([#787](https://github.com/mitmproxy/pdoc/pull/787), @iFreilicht)
 
 ## 2024-12-12: pdoc 15.0.1
 

pdoc/docstrings.py

@@ -193,13 +193,15 @@ def numpy(docstring: str) -> str:
     )
     contents = sections[0]
     for heading, content in zip(sections[1::2], sections[2::2]):
-        if content.startswith(" "):
+        if content.startswith(" ") and "\n" in content:
             # If the first line of section content is indented, we consider the section to be finished
             # on the first non-indented line. We take out the rest - the tail - here.
             content, tail = re.split(r"\n(?![ \n])", content, maxsplit=1)
         else:
             tail = ""
 
+        content = dedent(content)
+
         if heading in (
             "Parameters",
             "Returns",
@@ -214,7 +216,7 @@ def numpy(docstring: str) -> str:
         elif heading == "See Also":
             contents += f"###### {heading}\n{_numpy_seealso(content)}"
         else:
-            contents += f"###### {heading}\n{dedent(content)}"
+            contents += f"###### {heading}\n{content}"
         contents += tail
     return contents
 

test/testdata/flavors_numpy.html

@@ -101,6 +101,9 @@ <h2>API Documentation</h2>
             <li>
                     <a class="function" href="#invalid_format">invalid_format</a>
             </li>
+            <li>
+                    <a class="function" href="#invalid_format2">invalid_format2</a>
+            </li>
     </ul>
 
 
@@ -638,6 +641,15 @@ <h6 id="attributes">Attributes</h6>
 </span><span id="L-475"><a href="#L-475"><span class="linenos">475</span></a><span class="sd">    param1</span>
 </span><span id="L-476"><a href="#L-476"><span class="linenos">476</span></a>
 </span><span id="L-477"><a href="#L-477"><span class="linenos">477</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-478"><a href="#L-478"><span class="linenos">478</span></a>
+</span><span id="L-479"><a href="#L-479"><span class="linenos">479</span></a><span class="k">def</span><span class="w"> </span><span class="nf">invalid_format2</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+</span><span id="L-480"><a href="#L-480"><span class="linenos">480</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-481"><a href="#L-481"><span class="linenos">481</span></a><span class="sd">    Another example without description, but this time indented.</span>
+</span><span id="L-482"><a href="#L-482"><span class="linenos">482</span></a>
+</span><span id="L-483"><a href="#L-483"><span class="linenos">483</span></a><span class="sd">    Returns</span>
+</span><span id="L-484"><a href="#L-484"><span class="linenos">484</span></a><span class="sd">    -------</span>
+</span><span id="L-485"><a href="#L-485"><span class="linenos">485</span></a><span class="sd">        Text describing the return value.</span>
+</span><span id="L-486"><a href="#L-486"><span class="linenos">486</span></a><span class="sd">    &quot;&quot;&quot;</span>
 </span></pre></div>
 
 
@@ -1810,6 +1822,39 @@ <h6 id="parameters">Parameters</h6>
 </div>
 
 
+                </section>
+                <section id="invalid_format2">
+                            <input id="invalid_format2-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">invalid_format2</span><span class="signature pdoc-code condensed">(<span class="return-annotation">) -> <span class="kc">None</span>:</span></span>
+
+                <label class="view-source-button" for="invalid_format2-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#invalid_format2"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="invalid_format2-480"><a href="#invalid_format2-480"><span class="linenos">480</span></a><span class="k">def</span><span class="w"> </span><span class="nf">invalid_format2</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+</span><span id="invalid_format2-481"><a href="#invalid_format2-481"><span class="linenos">481</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="invalid_format2-482"><a href="#invalid_format2-482"><span class="linenos">482</span></a><span class="sd">    Another example without description, but this time indented.</span>
+</span><span id="invalid_format2-483"><a href="#invalid_format2-483"><span class="linenos">483</span></a>
+</span><span id="invalid_format2-484"><a href="#invalid_format2-484"><span class="linenos">484</span></a><span class="sd">    Returns</span>
+</span><span id="invalid_format2-485"><a href="#invalid_format2-485"><span class="linenos">485</span></a><span class="sd">    -------</span>
+</span><span id="invalid_format2-486"><a href="#invalid_format2-486"><span class="linenos">486</span></a><span class="sd">        Text describing the return value.</span>
+</span><span id="invalid_format2-487"><a href="#invalid_format2-487"><span class="linenos">487</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span></pre></div>
+
+
+            <div class="docstring"><p>Another example without description, but this time indented.</p>
+
+<h6 id="returns">Returns</h6>
+
+<ul>
+<li><strong>Text describing the return value.</strong></li>
+</ul>
+</div>
+
+
                 </section>
     </main>
 </body>

test/testdata/flavors_numpy.py

@@ -475,3 +475,12 @@ def invalid_format(test):
     param1
 
     """
+
+def invalid_format2() -> None:
+    """
+    Another example without description, but this time indented.
+
+    Returns
+    -------
+        Text describing the return value.
+    """

test/testdata/flavors_numpy.txt

@@ -26,4 +26,5 @@
     >
     <function def foo(var1, var2, *args, long_var_name='hi', **kwargs): ...  # Summarize the functi…>
     <function def invalid_format(test): ...  # In this example, the…>
+    <function def invalid_format2() -> None: ...  # Another example with…>
 >