hide empty constructors

mhils · Feb 19, 2023 · a269446 · a269446
1 parent 572fcfb
commit a269446
Show file tree

Hide file tree

Showing 11 changed files with 10 additions and 413 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 <!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
 
+ - pdoc now skips constructors if they neither have a docstring nor any parameters. This improves display
+   of classes that are not meant to be instantiated manually, for example when using PyO3.
  - Add a workaround to support inherited TypedDicts.
    ([#504](https://github.com/mitmproxy/pdoc/issues/504), @mhils)
  - `Variable.default_value_str` does not include the ` = ` prefix anymore. It will now emit a warning and return

diff --git a/pdoc/templates/default/module.html.jinja2 b/pdoc/templates/default/module.html.jinja2
@@ -227,8 +227,8 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     Implementing this as a macro makes it very easy to override with a custom template, see
     https://github.com/mitmproxy/pdoc/tree/main/examples/custom-template.
     #}
-    {% if doc.name == "__init__" %}
-        {# show all constructors #}
+    {% if doc.name == "__init__" and (doc.signature_without_self.parameters or doc.docstring) %}
+        {# show constructors that have a docstring or at least one extra argument #}
         true
     {% elif doc.name == "__doc__" %}
         {# We don't want to document __doc__ itself, https://github.com/mitmproxy/pdoc/issues/235 #}

diff --git a/test/testdata/demo_long.html b/test/testdata/demo_long.html
@@ -89,9 +89,6 @@ <h2>API Documentation</h2>
                         <li>
                                 <a class="class" href="#Bar.Baz">Bar.Baz</a>
                                         <ul class="memberlist">
-                                    <li>
-                                            <a class="function" href="#Bar.Baz.__init__">Baz</a>
-                                    </li>
                                     <li>
                                             <a class="function" href="#Bar.Baz.wat">wat</a>
                                     </li>
@@ -374,7 +371,7 @@ <h1 id="a-second-section">A Second Section</h1>
 </span><span id="L-158"><a href="#L-158"><span class="linenos">158</span></a><span class="sd">        It should be noted that inner classes are a pattern you most often want to avoid in Python.</span>
 </span><span id="L-159"><a href="#L-159"><span class="linenos">159</span></a><span class="sd">        Think about moving stuff in a new package instead!</span>
 </span><span id="L-160"><a href="#L-160"><span class="linenos">160</span></a>
-</span><span id="L-161"><a href="#L-161"><span class="linenos">161</span></a><span class="sd">        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).</span>
+</span><span id="L-161"><a href="#L-161"><span class="linenos">161</span></a><span class="sd">        This class has no __init__ method defined, so pdoc will not show a constructor.</span>
 </span><span id="L-162"><a href="#L-162"><span class="linenos">162</span></a><span class="sd">        &quot;&quot;&quot;</span>
 </span><span id="L-163"><a href="#L-163"><span class="linenos">163</span></a>
 </span><span id="L-164"><a href="#L-164"><span class="linenos">164</span></a>        <span class="k">def</span> <span class="nf">wat</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -896,7 +893,7 @@ <h1 id="a-second-section">A Second Section</h1>
 </span><span id="Bar-159"><a href="#Bar-159"><span class="linenos">159</span></a><span class="sd">        It should be noted that inner classes are a pattern you most often want to avoid in Python.</span>
 </span><span id="Bar-160"><a href="#Bar-160"><span class="linenos">160</span></a><span class="sd">        Think about moving stuff in a new package instead!</span>
 </span><span id="Bar-161"><a href="#Bar-161"><span class="linenos">161</span></a>
-</span><span id="Bar-162"><a href="#Bar-162"><span class="linenos">162</span></a><span class="sd">        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).</span>
+</span><span id="Bar-162"><a href="#Bar-162"><span class="linenos">162</span></a><span class="sd">        This class has no __init__ method defined, so pdoc will not show a constructor.</span>
 </span><span id="Bar-163"><a href="#Bar-163"><span class="linenos">163</span></a><span class="sd">        &quot;&quot;&quot;</span>
 </span><span id="Bar-164"><a href="#Bar-164"><span class="linenos">164</span></a>
 </span><span id="Bar-165"><a href="#Bar-165"><span class="linenos">165</span></a>        <span class="k">def</span> <span class="nf">wat</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -966,7 +963,7 @@ <h5>Inherited Members</h5>
 </span><span id="Bar.Baz-159"><a href="#Bar.Baz-159"><span class="linenos">159</span></a><span class="sd">        It should be noted that inner classes are a pattern you most often want to avoid in Python.</span>
 </span><span id="Bar.Baz-160"><a href="#Bar.Baz-160"><span class="linenos">160</span></a><span class="sd">        Think about moving stuff in a new package instead!</span>
 </span><span id="Bar.Baz-161"><a href="#Bar.Baz-161"><span class="linenos">161</span></a>
-</span><span id="Bar.Baz-162"><a href="#Bar.Baz-162"><span class="linenos">162</span></a><span class="sd">        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).</span>
+</span><span id="Bar.Baz-162"><a href="#Bar.Baz-162"><span class="linenos">162</span></a><span class="sd">        This class has no __init__ method defined, so pdoc will not show a constructor.</span>
 </span><span id="Bar.Baz-163"><a href="#Bar.Baz-163"><span class="linenos">163</span></a><span class="sd">        &quot;&quot;&quot;</span>
 </span><span id="Bar.Baz-164"><a href="#Bar.Baz-164"><span class="linenos">164</span></a>
 </span><span id="Bar.Baz-165"><a href="#Bar.Baz-165"><span class="linenos">165</span></a>        <span class="k">def</span> <span class="nf">wat</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -982,22 +979,10 @@ <h5>Inherited Members</h5>
 <p>It should be noted that inner classes are a pattern you most often want to avoid in Python.
 Think about moving stuff in a new package instead!</p>
 
-<p>Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).</p>
+<p>This class has no __init__ method defined, so pdoc will not show a constructor.</p>
 </div>
 
 
-                            <div id="Bar.Baz.__init__" class="classattr">
-                                <div class="attr function">
-
-        <span class="name">Bar.Baz</span><span class="signature pdoc-code condensed">()</span>
-
-
-    </div>
-    <a class="headerlink" href="#Bar.Baz.__init__"></a>
-
-
-
-                            </div>
                             <div id="Bar.Baz.wat" class="classattr">
                                         <input id="Bar.Baz.wat-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
 <div class="attr function">

diff --git a/test/testdata/demo_long.py b/test/testdata/demo_long.py
@@ -158,7 +158,7 @@ class Baz:
         It should be noted that inner classes are a pattern you most often want to avoid in Python.
         Think about moving stuff in a new package instead!
 
-        Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).
+        This class has no __init__ method defined, so pdoc will not show a constructor.
         """
 
         def wat(self):

diff --git a/test/testdata/demopackage.html b/test/testdata/demopackage.html
@@ -34,9 +34,6 @@ <h2>API Documentation</h2>
             <li>
                     <a class="class" href="#Test">Test</a>
                             <ul class="memberlist">
-                        <li>
-                                <a class="function" href="#Test.__init__">Test</a>
-                        </li>
                         <li>
                                 <a class="function" href="#Test.foo">foo</a>
                         </li>
@@ -46,9 +43,6 @@ <h2>API Documentation</h2>
             <li>
                     <a class="class" href="#B">B</a>
                             <ul class="memberlist">
-                        <li>
-                                <a class="function" href="#B.__init__">B</a>
-                        </li>
                         <li>
                                 <a class="variable" href="#B.b_type">b_type</a>
                         </li>
@@ -61,9 +55,6 @@ <h2>API Documentation</h2>
             <li>
                     <a class="class" href="#C">C</a>
                             <ul class="memberlist">
-                        <li>
-                                <a class="function" href="#C.__init__">C</a>
-                        </li>
                         <li>
                                 <a class="function" href="#C.c">c</a>
                         </li>
@@ -142,18 +133,6 @@ <h1 class="modulename">
 </div>
 
 
-                            <div id="Test.__init__" class="classattr">
-                                <div class="attr function">
-
-        <span class="name">Test</span><span class="signature pdoc-code condensed">()</span>
-
-
-    </div>
-    <a class="headerlink" href="#Test.__init__"></a>
-
-
-
-                            </div>
                             <div id="Test.foo" class="classattr">
                                         <input id="Test.foo-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
 <div class="attr function">
@@ -202,18 +181,6 @@ <h1 class="modulename">
 </div>
 
 
-                            <div id="B.__init__" class="classattr">
-                                <div class="attr function">
-
-        <span class="name">B</span><span class="signature pdoc-code condensed">()</span>
-
-
-    </div>
-    <a class="headerlink" href="#B.__init__"></a>
-
-
-
-                            </div>
                             <div id="B.b_type" class="classattr">
                                 <div class="attr variable">
             <span class="name">b_type</span><span class="annotation">: Type[<a href="#B">demopackage.B</a>]</span>
@@ -270,18 +237,6 @@ <h1 class="modulename">
 </div>
 
 
-                            <div id="C.__init__" class="classattr">
-                                <div class="attr function">
-
-        <span class="name">C</span><span class="signature pdoc-code condensed">()</span>
-
-
-    </div>
-    <a class="headerlink" href="#C.__init__"></a>
-
-
-
-                            </div>
                             <div id="C.c" class="classattr">
                                         <input id="C.c-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
 <div class="attr function">

diff --git a/test/testdata/demopackage_dir.html b/test/testdata/demopackage_dir.html