Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document enum mebers without docstring #457

Merged
merged 2 commits into from
Nov 10, 2022
Merged

Document enum mebers without docstring #457

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
08c565c
document enum members without docstring, fix #455
mhils Nov 10, 2022
f1e0a59
[autofix.ci] apply automated fixes
autofix-ci[bot] Nov 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

- Fix a CSS issue for overflowing math equations.
([#456](https://github.com/mitmproxy/pdoc/pull/456), @mhils)
- Fix a regression from poc 12.2: Enum members are now always documented
even if they do not have a docstring.
([#457](https://github.com/mitmproxy/pdoc/pull/457), @mhils)

## 2022-11-05: pdoc 12.2.1

Expand Down
8 changes: 8 additions & 0 deletions pdoc/doc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1030,6 +1030,14 @@ def is_classvar(self) -> bool:
else:
return False

@cached_property
def is_enum_member(self) -> bool:
"""`True` if the variable is an enum member, `False` otherwise."""
if isinstance(self.default_value, enum.Enum):
return True
else:
return False

@cached_property
def default_value_str(self) -> str:
"""The variable's default value as a pretty-printed str."""
Expand Down
2 changes: 1 addition & 1 deletion pdoc/templates/default/module.html.jinja2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
{% elif (doc.qualname or doc.name) is in(module.obj.__all__ or []) %}
{# members starting with an underscore are still public if mentioned in __all__ #}
true
{% elif not doc.name.startswith("_") and (doc.kind != "variable" or doc.docstring) %}
{% elif not doc.name.startswith("_") and (doc.kind != "variable" or doc.is_enum_member or doc.docstring) %}
{# members not starting with an underscore are considered public by default #}
true
{% endif %}
Expand Down
4 changes: 2 additions & 2 deletions test/test_snapshot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,14 +176,14 @@ def test_snapshots(snapshot: Snapshot, format: str, monkeypatch):
os.chdir(snapshot_dir)
skipped_some = False
for snapshot in snapshots:
if len(sys.argv) > 1 and snapshot.id not in sys.argv:
continue
if sys.version_info < snapshot.min_version:
print(
f"Skipping {snapshot} as it requires a more recent version of Python."
)
skipped_some = True
continue
if len(sys.argv) > 1 and snapshot.id not in sys.argv:
continue
for format in ["html", "repr"]:
print(f"Rendering {snapshot} to {format}...")
rendered = snapshot.make(format)
Expand Down
84 changes: 40 additions & 44 deletions test/testdata/demo_long.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -456,28 +456,27 @@ <h1 id="a-second-section">A Second Section</h1>
</span><span id="L-243"><a href="#L-243"><span class="linenos">243</span></a> <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>
</span><span id="L-244"><a href="#L-244"><span class="linenos">244</span></a> <span class="sd">&quot;&quot;&quot;I am green.&quot;&quot;&quot;</span>
</span><span id="L-245"><a href="#L-245"><span class="linenos">245</span></a> <span class="n">BLUE</span> <span class="o">=</span> <span class="n">enum</span><span class="o">.</span><span class="n">auto</span><span class="p">()</span>
</span><span id="L-246"><a href="#L-246"><span class="linenos">246</span></a> <span class="sd">&quot;&quot;&quot;I am blue.&quot;&quot;&quot;</span>
</span><span id="L-246"><a href="#L-246"><span class="linenos">246</span></a>
</span><span id="L-247"><a href="#L-247"><span class="linenos">247</span></a>
</span><span id="L-248"><a href="#L-248"><span class="linenos">248</span></a>
</span><span id="L-249"><a href="#L-249"><span class="linenos">249</span></a><span class="k">def</span> <span class="nf">admonitions</span><span class="p">():</span>
</span><span id="L-250"><a href="#L-250"><span class="linenos">250</span></a> <span class="sd">&quot;&quot;&quot;</span>
</span><span id="L-251"><a href="#L-251"><span class="linenos">251</span></a><span class="sd"> pdoc also supports basic reStructuredText admonitions:</span>
</span><span id="L-252"><a href="#L-252"><span class="linenos">252</span></a>
</span><span id="L-253"><a href="#L-253"><span class="linenos">253</span></a><span class="sd"> ```</span>
</span><span id="L-254"><a href="#L-254"><span class="linenos">254</span></a><span class="sd"> .. note/warning/danger:: Optional title</span>
</span><span id="L-255"><a href="#L-255"><span class="linenos">255</span></a><span class="sd"> Body text</span>
</span><span id="L-256"><a href="#L-256"><span class="linenos">256</span></a><span class="sd"> ```</span>
</span><span id="L-257"><a href="#L-257"><span class="linenos">257</span></a>
</span><span id="L-258"><a href="#L-258"><span class="linenos">258</span></a><span class="sd"> .. note::</span>
</span><span id="L-259"><a href="#L-259"><span class="linenos">259</span></a><span class="sd"> Hi there!</span>
</span><span id="L-260"><a href="#L-260"><span class="linenos">260</span></a>
</span><span id="L-261"><a href="#L-261"><span class="linenos">261</span></a><span class="sd"> .. warning:: Be Careful!</span>
</span><span id="L-262"><a href="#L-262"><span class="linenos">262</span></a><span class="sd"> This warning has both a title and content.</span>
</span><span id="L-263"><a href="#L-263"><span class="linenos">263</span></a>
</span><span id="L-264"><a href="#L-264"><span class="linenos">264</span></a><span class="sd"> .. danger::</span>
</span><span id="L-265"><a href="#L-265"><span class="linenos">265</span></a><span class="sd"> Danger ahead.</span>
</span><span id="L-266"><a href="#L-266"><span class="linenos">266</span></a>
</span><span id="L-267"><a href="#L-267"><span class="linenos">267</span></a><span class="sd"> &quot;&quot;&quot;</span>
</span><span id="L-248"><a href="#L-248"><span class="linenos">248</span></a><span class="k">def</span> <span class="nf">admonitions</span><span class="p">():</span>
</span><span id="L-249"><a href="#L-249"><span class="linenos">249</span></a> <span class="sd">&quot;&quot;&quot;</span>
</span><span id="L-250"><a href="#L-250"><span class="linenos">250</span></a><span class="sd"> pdoc also supports basic reStructuredText admonitions:</span>
</span><span id="L-251"><a href="#L-251"><span class="linenos">251</span></a>
</span><span id="L-252"><a href="#L-252"><span class="linenos">252</span></a><span class="sd"> ```</span>
</span><span id="L-253"><a href="#L-253"><span class="linenos">253</span></a><span class="sd"> .. note/warning/danger:: Optional title</span>
</span><span id="L-254"><a href="#L-254"><span class="linenos">254</span></a><span class="sd"> Body text</span>
</span><span id="L-255"><a href="#L-255"><span class="linenos">255</span></a><span class="sd"> ```</span>
</span><span id="L-256"><a href="#L-256"><span class="linenos">256</span></a>
</span><span id="L-257"><a href="#L-257"><span class="linenos">257</span></a><span class="sd"> .. note::</span>
</span><span id="L-258"><a href="#L-258"><span class="linenos">258</span></a><span class="sd"> Hi there!</span>
</span><span id="L-259"><a href="#L-259"><span class="linenos">259</span></a>
</span><span id="L-260"><a href="#L-260"><span class="linenos">260</span></a><span class="sd"> .. warning:: Be Careful!</span>
</span><span id="L-261"><a href="#L-261"><span class="linenos">261</span></a><span class="sd"> This warning has both a title and content.</span>
</span><span id="L-262"><a href="#L-262"><span class="linenos">262</span></a>
</span><span id="L-263"><a href="#L-263"><span class="linenos">263</span></a><span class="sd"> .. danger::</span>
</span><span id="L-264"><a href="#L-264"><span class="linenos">264</span></a><span class="sd"> Danger ahead.</span>
</span><span id="L-265"><a href="#L-265"><span class="linenos">265</span></a>
</span><span id="L-266"><a href="#L-266"><span class="linenos">266</span></a><span class="sd"> &quot;&quot;&quot;</span>
</span></pre></div>


Expand Down Expand Up @@ -1311,7 +1310,6 @@ <h5>Inherited Members</h5>
</span><span id="EnumDemo-244"><a href="#EnumDemo-244"><span class="linenos">244</span></a> <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>
</span><span id="EnumDemo-245"><a href="#EnumDemo-245"><span class="linenos">245</span></a> <span class="sd">&quot;&quot;&quot;I am green.&quot;&quot;&quot;</span>
</span><span id="EnumDemo-246"><a href="#EnumDemo-246"><span class="linenos">246</span></a> <span class="n">BLUE</span> <span class="o">=</span> <span class="n">enum</span><span class="o">.</span><span class="n">auto</span><span class="p">()</span>
</span><span id="EnumDemo-247"><a href="#EnumDemo-247"><span class="linenos">247</span></a> <span class="sd">&quot;&quot;&quot;I am blue.&quot;&quot;&quot;</span>
</span></pre></div>


Expand Down Expand Up @@ -1355,9 +1353,7 @@ <h5>Inherited Members</h5>
</div>
<a class="headerlink" href="#EnumDemo.BLUE"></a>

<div class="docstring"><p>I am blue.</p>
</div>



</div>
<div class="inherited">
Expand All @@ -1382,25 +1378,25 @@ <h5>Inherited Members</h5>

</div>
<a class="headerlink" href="#admonitions"></a>
<div class="pdoc-code codehilite"><pre><span></span><span id="admonitions-250"><a href="#admonitions-250"><span class="linenos">250</span></a><span class="k">def</span> <span class="nf">admonitions</span><span class="p">():</span>
</span><span id="admonitions-251"><a href="#admonitions-251"><span class="linenos">251</span></a> <span class="sd">&quot;&quot;&quot;</span>
</span><span id="admonitions-252"><a href="#admonitions-252"><span class="linenos">252</span></a><span class="sd"> pdoc also supports basic reStructuredText admonitions:</span>
</span><span id="admonitions-253"><a href="#admonitions-253"><span class="linenos">253</span></a>
</span><span id="admonitions-254"><a href="#admonitions-254"><span class="linenos">254</span></a><span class="sd"> ```</span>
</span><span id="admonitions-255"><a href="#admonitions-255"><span class="linenos">255</span></a><span class="sd"> .. note/warning/danger:: Optional title</span>
</span><span id="admonitions-256"><a href="#admonitions-256"><span class="linenos">256</span></a><span class="sd"> Body text</span>
</span><span id="admonitions-257"><a href="#admonitions-257"><span class="linenos">257</span></a><span class="sd"> ```</span>
</span><span id="admonitions-258"><a href="#admonitions-258"><span class="linenos">258</span></a>
</span><span id="admonitions-259"><a href="#admonitions-259"><span class="linenos">259</span></a><span class="sd"> .. note::</span>
</span><span id="admonitions-260"><a href="#admonitions-260"><span class="linenos">260</span></a><span class="sd"> Hi there!</span>
</span><span id="admonitions-261"><a href="#admonitions-261"><span class="linenos">261</span></a>
</span><span id="admonitions-262"><a href="#admonitions-262"><span class="linenos">262</span></a><span class="sd"> .. warning:: Be Careful!</span>
</span><span id="admonitions-263"><a href="#admonitions-263"><span class="linenos">263</span></a><span class="sd"> This warning has both a title and content.</span>
</span><span id="admonitions-264"><a href="#admonitions-264"><span class="linenos">264</span></a>
</span><span id="admonitions-265"><a href="#admonitions-265"><span class="linenos">265</span></a><span class="sd"> .. danger::</span>
</span><span id="admonitions-266"><a href="#admonitions-266"><span class="linenos">266</span></a><span class="sd"> Danger ahead.</span>
</span><span id="admonitions-267"><a href="#admonitions-267"><span class="linenos">267</span></a>
</span><span id="admonitions-268"><a href="#admonitions-268"><span class="linenos">268</span></a><span class="sd"> &quot;&quot;&quot;</span>
<div class="pdoc-code codehilite"><pre><span></span><span id="admonitions-249"><a href="#admonitions-249"><span class="linenos">249</span></a><span class="k">def</span> <span class="nf">admonitions</span><span class="p">():</span>
</span><span id="admonitions-250"><a href="#admonitions-250"><span class="linenos">250</span></a> <span class="sd">&quot;&quot;&quot;</span>
</span><span id="admonitions-251"><a href="#admonitions-251"><span class="linenos">251</span></a><span class="sd"> pdoc also supports basic reStructuredText admonitions:</span>
</span><span id="admonitions-252"><a href="#admonitions-252"><span class="linenos">252</span></a>
</span><span id="admonitions-253"><a href="#admonitions-253"><span class="linenos">253</span></a><span class="sd"> ```</span>
</span><span id="admonitions-254"><a href="#admonitions-254"><span class="linenos">254</span></a><span class="sd"> .. note/warning/danger:: Optional title</span>
</span><span id="admonitions-255"><a href="#admonitions-255"><span class="linenos">255</span></a><span class="sd"> Body text</span>
</span><span id="admonitions-256"><a href="#admonitions-256"><span class="linenos">256</span></a><span class="sd"> ```</span>
</span><span id="admonitions-257"><a href="#admonitions-257"><span class="linenos">257</span></a>
</span><span id="admonitions-258"><a href="#admonitions-258"><span class="linenos">258</span></a><span class="sd"> .. note::</span>
</span><span id="admonitions-259"><a href="#admonitions-259"><span class="linenos">259</span></a><span class="sd"> Hi there!</span>
</span><span id="admonitions-260"><a href="#admonitions-260"><span class="linenos">260</span></a>
</span><span id="admonitions-261"><a href="#admonitions-261"><span class="linenos">261</span></a><span class="sd"> .. warning:: Be Careful!</span>
</span><span id="admonitions-262"><a href="#admonitions-262"><span class="linenos">262</span></a><span class="sd"> This warning has both a title and content.</span>
</span><span id="admonitions-263"><a href="#admonitions-263"><span class="linenos">263</span></a>
</span><span id="admonitions-264"><a href="#admonitions-264"><span class="linenos">264</span></a><span class="sd"> .. danger::</span>
</span><span id="admonitions-265"><a href="#admonitions-265"><span class="linenos">265</span></a><span class="sd"> Danger ahead.</span>
</span><span id="admonitions-266"><a href="#admonitions-266"><span class="linenos">266</span></a>
</span><span id="admonitions-267"><a href="#admonitions-267"><span class="linenos">267</span></a><span class="sd"> &quot;&quot;&quot;</span>
</span></pre></div>


Expand Down
1 change: 0 additions & 1 deletion test/testdata/demo_long.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,6 @@ class EnumDemo(enum.Enum):
GREEN = 2
"""I am green."""
BLUE = enum.auto()
"""I am blue."""


def admonitions():
Expand Down
2 changes: 1 addition & 1 deletion test/testdata/demo_long.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ This …
<class demo_long.EnumDemo # This is an example o…
<var RED = <EnumDemo.RED: 1> # I am the red.>
<var GREEN = <EnumDemo.GREEN: 2> # I am green.>
<var BLUE = <EnumDemo.BLUE: 3> # I am blue.>
<var BLUE = <EnumDemo.BLUE: 3>>
<var name # inherited from enum.Enum.name, The name of the Enum…>
<var value # inherited from enum.Enum.value, The value of the Enu…>>
<function def admonitions(): ... # pdoc also supports b…>>