only document variables with a docstring attached, fix mitmproxy#411

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 # Unreleased: pdoc next
 
+ - Make documentation of variables more consistent. Variables with a default value
+   and no docstring are now hidden, matching the behavior of variables with a type annotation only.
+   ([#411](https://github.com/mitmproxy/pdoc/issues/411), [@mhils](https://github.com/mhils))
  - Remove `format` argument from `pdoc.pdoc()`. For the forseeable future, pdoc will only support HTML export.
    ([#308](https://github.com/mitmproxy/pdoc/issues/308), [@mhils](https://github.com/mhils))
  - Update vendored copy of markdown2.

pdoc/doc.py

@@ -659,6 +659,8 @@ def _member_objects(self) -> dict[str, Any]:
                 unsorted.setdefault(name, obj)
         for name in self._var_docstrings:
             unsorted.setdefault(name, empty)
+        for name in self._var_annotations:
+            unsorted.setdefault(name, empty)
 
         init_has_no_doc = unsorted.get("__init__", object.__init__).__doc__ in (
             None,

pdoc/templates/default/module.html.jinja2

@@ -224,24 +224,22 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     {#
     This macro is a bit unconventional in that its output is not rendered, but treated as a boolean:
     Returning no text is interpreted as false, returning any other text is iterpreted as true.
-    Implementing this as a macro makes it very easy to override with a custom template.
+    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.type == "module" and doc.fullname not in all_modules %}
-        {# Don't document modules that were manually excluded from the documentation #}
-        {# https://github.com/mitmproxy/pdoc/issues/334 #}
-    {% elif not doc.name.startswith("_") %}
-        {# members not starting with an underscore are considered public by default #}
-        true
-    {% elif doc.name == "__init__" %}
-        {# the constructor is our special case which we also treat as public #}
+    {% if doc.name == "__init__" %}
+        {# show all constructors #}
         true
+    {% elif doc.name == "__doc__" %}
+        {# We don't want to document __doc__ itself, https://github.com/mitmproxy/pdoc/issues/235 #}
+    {% elif doc.type == "module" and doc.fullname not in all_modules %}
+        {# Skip modules that were manually excluded, https://github.com/mitmproxy/pdoc/issues/334 #}
     {% elif (doc.qualname or doc.name) is in(module.obj.__all__ or []) %}
         {# members starting with an underscore are still public if mentioned in __all__ #}
-        {% if doc.name != "__doc__" %}
-            {# ... but sometimes we have __doc__ in __all__, which we want to exclude for pdoc's purposes. #}
-            {# https://github.com/mitmproxy/pdoc/issues/235 #}
-            true
-        {% endif %}
+        true
+    {% elif not doc.name.startswith("_") and (doc.type != "variable" or doc.docstring) %}
+        {# members not starting with an underscore are considered public by default #}
+        true
     {% endif %}
 {% enddefaultmacro %}
 {# fmt: off #}

test/testdata/demo_long.py

@@ -209,6 +209,10 @@ class DataDemo:
     """Again, we can document individual properties with docstrings."""
     a2: Sequence[str]
     # This property has a type annotation but is not documented.
+    a3 = "a3"
+    # This property has a default value but is not documented.
+    a4: str = "a4"
+    # This property has a type annotation and a default value but is not documented.
     b: bool = field(repr=False, default=True)
     """This property is assigned to `dataclasses.field()`, which works just as well."""
 

test/testdata/demo_long.txt

@@ -56,13 +56,26 @@ This …
         <method def wat(self): ...  # inherited from demo_long.Bar.Baz.wat, A regular method. Ab…>>
     <var CONST_B = 'yes'  # A constant without t…>
     <@dataclass class demo_long.DataDemo  # This is an example f…
-        <method def __init__(self, a: int, a2: Sequence[str], b: bool = True): ...>
+        <method def __init__(self, a: int, a2: Sequence[str], a4: str = 'wat', b: bool = True): ...>
         <var a: int  # Again, we can docume…>
+        <var a2: Sequence[str]>
+        <var a3 = 'wat'>
+        <var a4: str = 'wat'>
         <var b: bool = True  # This property is ass…>>
     <@dataclass class demo_long.DataDemoExtended
-        <method def __init__(self, a: int, a2: Sequence[str], b: bool = True, c: str = '42'): ...>
+        <method def __init__(
+            self,
+            a: int,
+            a2: Sequence[str],
+            a4: str = 'wat',
+            b: bool = True,
+            c: str = '42'
+        ): ...>
         <var c: str = '42'  # A new attribute.>
         <var a: int  # inherited from demo_long.DataDemo.a, Again, we can docume…>
+        <var a2: Sequence[str]  # inherited from demo_long.DataDemo.a2>
+        <var a3 = 'wat'  # inherited from demo_long.DataDemo.a3>
+        <var a4: str = 'wat'  # inherited from demo_long.DataDemo.a4>
         <var b: bool = True  # inherited from demo_long.DataDemo.b, This property is ass…>>
     <class demo_long.EnumDemo  # This is an example o…
         <var RED = <EnumDemo.RED: 1>  # I am the red.>

test/testdata/flavors_google.html

@@ -1010,7 +1010,6 @@ <h5>Inherited Members</h5>
                                 <dl>
                                     <div><dt>builtins.BaseException</dt>
                                 <dd id="ExampleError.with_traceback" class="function">with_traceback</dd>
-                <dd id="ExampleError.args" class="variable">args</dd>
 
             </div>
                                 </dl>

test/testdata/flavors_numpy.html

@@ -1078,7 +1078,6 @@ <h5>Inherited Members</h5>
                                 <dl>
                                     <div><dt>builtins.BaseException</dt>
                                 <dd id="ExampleError.with_traceback" class="function">with_traceback</dd>
-                <dd id="ExampleError.args" class="variable">args</dd>
 
             </div>
                                 </dl>

test/testdata/misc_py311.html

@@ -89,7 +89,6 @@ <h5>Inherited Members</h5>
             <div><dt>builtins.BaseException</dt>
                                 <dd id="CustomException.with_traceback" class="function">with_traceback</dd>
                 <dd id="CustomException.add_note" class="function">add_note</dd>
-                <dd id="CustomException.args" class="variable">args</dd>
 
             </div>
                                 </dl>

test/testdata/misc_py39.txt

@@ -20,6 +20,7 @@
         <method def copy(unknown): ...  # inherited from builtins.dict.copy, D.copy() -> a shallo…>>
     <class misc_py39.Bar  # A TypedDict subclass…
         <var b: int  # Second attribute.>
+        <var c: str>
         <method def get(self, key, default=None, /): ...  # inherited from builtins.dict.get, Return the value for…>
         <method def setdefault(self, key, default=None, /): ...  # inherited from builtins.dict.setdefault, Insert key with a va…>
         <method def pop(unknown): ...  # inherited from builtins.dict.pop, D.pop(k[,d]) -> v, r…>
@@ -30,7 +31,8 @@
         <method def update(unknown): ...  # inherited from builtins.dict.update, D.update([E, ]**F) -…>
         <method def fromkeys(type, iterable, value=None, /): ...  # inherited from builtins.dict.fromkeys, Create a new diction…>
         <method def clear(unknown): ...  # inherited from builtins.dict.clear, D.clear() -> None.  …>
-        <method def copy(unknown): ...  # inherited from builtins.dict.copy, D.copy() -> a shallo…>>
+        <method def copy(unknown): ...  # inherited from builtins.dict.copy, D.copy() -> a shallo…>
+        <var a: Optional[int]>>
     <class misc_py39.SingleDispatchMethodExample
         <method def __init__(): ...>
         <@functools.singledispatchmethod method def fancymethod(self, str_or_int: Union[str, int]): ...  # A fancy method which…>

test/testdata/type_checking_imports.html

@@ -63,10 +63,11 @@ <h1 class="modulename">
 </span><span id="L-11"><a href="#L-11"><span class="linenos">11</span></a>
 </span><span id="L-12"><a href="#L-12"><span class="linenos">12</span></a>
 </span><span id="L-13"><a href="#L-13"><span class="linenos">13</span></a><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="n">b</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]):</span>
-</span><span id="L-14"><a href="#L-14"><span class="linenos">14</span></a>    <span class="k">pass</span>
+</span><span id="L-14"><a href="#L-14"><span class="linenos">14</span></a>    <span class="sd">&quot;&quot;&quot;A method with TYPE_CHECKING type annotations.&quot;&quot;&quot;</span>
 </span><span id="L-15"><a href="#L-15"><span class="linenos">15</span></a>
 </span><span id="L-16"><a href="#L-16"><span class="linenos">16</span></a>
 </span><span id="L-17"><a href="#L-17"><span class="linenos">17</span></a><span class="n">var</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
+</span><span id="L-18"><a href="#L-18"><span class="linenos">18</span></a><span class="sd">&quot;&quot;&quot;A variable with TYPE_CHECKING type annotations.&quot;&quot;&quot;</span>
 </span></pre></div>
 
 
@@ -83,11 +84,13 @@ <h1 class="modulename">
     </div>
     <a class="headerlink" href="#foo"></a>
             <div class="pdoc-code codehilite"><pre><span></span><span id="foo-14"><a href="#foo-14"><span class="linenos">14</span></a><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="n">b</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]):</span>
-</span><span id="foo-15"><a href="#foo-15"><span class="linenos">15</span></a>    <span class="k">pass</span>
+</span><span id="foo-15"><a href="#foo-15"><span class="linenos">15</span></a>    <span class="sd">&quot;&quot;&quot;A method with TYPE_CHECKING type annotations.&quot;&quot;&quot;</span>
 </span></pre></div>
 
 
-
+            <div class="docstring"><p>A method with TYPE_CHECKING type annotations.</p>
+</div>
+
 
                 </section>
                 <section id="var">
@@ -98,7 +101,9 @@ <h1 class="modulename">
     </div>
     <a class="headerlink" href="#var"></a>
 
-
+            <div class="docstring"><p>A variable with TYPE_CHECKING type annotations.</p>
+</div>
+
 
                 </section>
     </main>

test/testdata/type_checking_imports.py

@@ -11,7 +11,8 @@
 
 
 def foo(a: Sequence[str], b: Dict[str, str]):
-    pass
+    """A method with TYPE_CHECKING type annotations."""
 
 
 var: Sequence[int] = (1, 2, 3)
+"""A variable with TYPE_CHECKING type annotations."""

test/testdata/type_checking_imports.txt

@@ -1,3 +1,3 @@
 <module type_checking_imports
-    <function def foo(a: Sequence[str], b: Dict[str, str]): ...>
-    <var var: Sequence[int] = (1, 2, 3)>>
+    <function def foo(a: Sequence[str], b: Dict[str, str]): ...  # A method with TYPE_C…>
+    <var var: Sequence[int] = (1, 2, 3)  # A variable with TYPE…>>