From 08c565cb95eec20aca69e995089c6758bc2ef47a Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Thu, 10 Nov 2022 13:05:57 +0100 Subject: [PATCH] document enum members without docstring, fix #455 --- CHANGELOG.md | 2 + pdoc/doc.py | 8 +++ pdoc/templates/default/module.html.jinja2 | 2 +- test/test_snapshot.py | 4 +- test/testdata/demo_long.html | 84 +++++++++++------------ test/testdata/demo_long.py | 1 - test/testdata/demo_long.txt | 2 +- 7 files changed, 54 insertions(+), 49 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9123845e..b2ee02ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ - 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. ## 2022-11-05: pdoc 12.2.1 diff --git a/pdoc/doc.py b/pdoc/doc.py index 54174a94..13dd096e 100644 --- a/pdoc/doc.py +++ b/pdoc/doc.py @@ -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.""" diff --git a/pdoc/templates/default/module.html.jinja2 b/pdoc/templates/default/module.html.jinja2 index 059face7..7097d76a 100644 --- a/pdoc/templates/default/module.html.jinja2 +++ b/pdoc/templates/default/module.html.jinja2 @@ -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 %} diff --git a/test/test_snapshot.py b/test/test_snapshot.py index 3ec082ad..7105dbd6 100755 --- a/test/test_snapshot.py +++ b/test/test_snapshot.py @@ -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) diff --git a/test/testdata/demo_long.html b/test/testdata/demo_long.html index e86aae5c..1b4ba1d3 100644 --- a/test/testdata/demo_long.html +++ b/test/testdata/demo_long.html @@ -456,28 +456,27 @@

A Second Section

243 GREEN = 2 244 """I am green.""" 245 BLUE = enum.auto() -246 """I am blue.""" +246 247 -248 -249def admonitions(): -250 """ -251 pdoc also supports basic reStructuredText admonitions: -252 -253 ``` -254 .. note/warning/danger:: Optional title -255 Body text -256 ``` -257 -258 .. note:: -259 Hi there! -260 -261 .. warning:: Be Careful! -262 This warning has both a title and content. -263 -264 .. danger:: -265 Danger ahead. -266 -267 """ +248def admonitions(): +249 """ +250 pdoc also supports basic reStructuredText admonitions: +251 +252 ``` +253 .. note/warning/danger:: Optional title +254 Body text +255 ``` +256 +257 .. note:: +258 Hi there! +259 +260 .. warning:: Be Careful! +261 This warning has both a title and content. +262 +263 .. danger:: +264 Danger ahead. +265 +266 """ @@ -1311,7 +1310,6 @@
Inherited Members
244 GREEN = 2 245 """I am green.""" 246 BLUE = enum.auto() -247 """I am blue.""" @@ -1355,9 +1353,7 @@
Inherited Members
-

I am blue.

-
- +
@@ -1382,25 +1378,25 @@
Inherited Members
- 
250def admonitions():
-251    """
-252    pdoc also supports basic reStructuredText admonitions:
-253
-254    ```
-255    .. note/warning/danger:: Optional title
-256       Body text
-257    ```
-258
-259    .. note::
-260       Hi there!
-261
-262    .. warning:: Be Careful!
-263       This warning has both a title and content.
-264
-265    .. danger::
-266       Danger ahead.
-267
-268    """
+            
249def admonitions():
+250    """
+251    pdoc also supports basic reStructuredText admonitions:
+252
+253    ```
+254    .. note/warning/danger:: Optional title
+255       Body text
+256    ```
+257
+258    .. note::
+259       Hi there!
+260
+261    .. warning:: Be Careful!
+262       This warning has both a title and content.
+263
+264    .. danger::
+265       Danger ahead.
+266
+267    """
 

 
 
diff --git a/test/testdata/demo_long.py b/test/testdata/demo_long.py
index 9a8875b3..fa87f648 100644
--- a/test/testdata/demo_long.py
+++ b/test/testdata/demo_long.py
@@ -243,7 +243,6 @@ class EnumDemo(enum.Enum):
     GREEN = 2
     """I am green."""
     BLUE = enum.auto()
-    """I am blue."""
 
 
 def admonitions():
diff --git a/test/testdata/demo_long.txt b/test/testdata/demo_long.txt
index b38f550a..628d48b8 100644
--- a/test/testdata/demo_long.txt
+++ b/test/testdata/demo_long.txt
@@ -80,7 +80,7 @@ This …
       # I am the red.>
           # I am green.>
-          # I am blue.>
+        >
         
         >
     >
\ No newline at end of file