From 44ece4c19f789f0618a4c6db8d37eb95863c4d45 Mon Sep 17 00:00:00 2001 From: tmeyier <95271082+tmeyier@users.noreply.github.com> Date: Fri, 22 Dec 2023 23:51:06 +0100 Subject: [PATCH] show source code for properties (#654) --- CHANGELOG.md | 2 ++ pdoc/doc.py | 3 +++ test/testdata/demo_long.html | 43 ++++++++++++++++++++++++------- test/testdata/flavors_google.html | 33 +++++++++++++++++++----- test/testdata/flavors_numpy.html | 33 +++++++++++++++++++----- test/testdata/misc.html | 26 ++++++++++++++----- 6 files changed, 113 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d7eca99d..eec8ae78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ - Improve rendering of `.pyi` type stubs containing `@typing.overload`. ([#652](https://github.com/mitmproxy/pdoc/pull/652), @mhils) + - `@property` and `@cached_property` attributes now have a "View Source" button. + ([#654](https://github.com/mitmproxy/pdoc/pull/654), @tmeyier) ## 2023-12-13: pdoc 14.2.0 diff --git a/pdoc/doc.py b/pdoc/doc.py index cbe2f8fe..cfee58ca 100644 --- a/pdoc/doc.py +++ b/pdoc/doc.py @@ -283,6 +283,9 @@ def members(self) -> dict[str, Doc]: default_value=empty, taken_from=taken_from, ) + doc.source = doc_f.source + doc.source_file = doc_f.source_file + doc.source_lines = doc_f.source_lines elif inspect.isroutine(obj): doc = Function(self.modulename, qualname, obj, taken_from) # type: ignore elif ( diff --git a/test/testdata/demo_long.html b/test/testdata/demo_long.html index c4ca214e..dd015e49 100644 --- a/test/testdata/demo_long.html +++ b/test/testdata/demo_long.html @@ -800,26 +800,42 @@

A Second Section

-
+ +
a_property: str - + +
- + 
117    @property
+118    def a_property(self) -> str:
+119        """This is a `@property` attribute. pdoc will display it as a variable."""
+120        return "true foo"
+
+ +

This is a @property attribute. pdoc will display it as a variable.

-
+ +
a_cached_property: str - + +
- + 
122    @cached_property
+123    def a_cached_property(self) -> str:
+124        """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well."""
+125        return "true foo"
+
+ +

This is a @functools.cached_property attribute. pdoc will display it as a variable as well.

@@ -874,13 +890,22 @@

A Second Section

-
+ +
a_class_property: int - + +
- + 
137    @classmethod  # type: ignore
+138    @property
+139    def a_class_property(cls) -> int:
+140        """This is what a `@classmethod @property` looks like."""
+141        return 24
+
+ +

This is what a @classmethod @property looks like.

diff --git a/test/testdata/flavors_google.html b/test/testdata/flavors_google.html index 212f26ca..a4f8b9ce 100644 --- a/test/testdata/flavors_google.html +++ b/test/testdata/flavors_google.html @@ -1384,26 +1384,47 @@
Arguments:
-
+ +
readonly_property - + +
- + 
244    @property
+245    def readonly_property(self):
+246        """str: Properties should be documented in their getter method."""
+247        return 'readonly_property'
+
+ +

str: Properties should be documented in their getter method.

-
+ +
readwrite_property - + +
- + 
249    @property
+250    def readwrite_property(self):
+251        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
+252        should only be documented in their getter method.
+253
+254        If the setter method contains notable behavior, it should be
+255        mentioned here.
+256        """
+257        return ['readwrite_property']
+
+ +

list of str: Properties with both a getter and setter should only be documented in their getter method.

diff --git a/test/testdata/flavors_numpy.html b/test/testdata/flavors_numpy.html index df5e6345..1efbfea8 100644 --- a/test/testdata/flavors_numpy.html +++ b/test/testdata/flavors_numpy.html @@ -1439,26 +1439,47 @@
Parameters
-
+ +
readonly_property - + +
- + 
295    @property
+296    def readonly_property(self):
+297        """str: Properties should be documented in their getter method."""
+298        return "readonly_property"
+
+ +

str: Properties should be documented in their getter method.

-
+ +
readwrite_property - + +
- + 
300    @property
+301    def readwrite_property(self):
+302        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
+303        should only be documented in their getter method.
+304
+305        If the setter method contains notable behavior, it should be
+306        mentioned here.
+307        """
+308        return ["readwrite_property"]
+
+ +

list of str: Properties with both a getter and setter should only be documented in their getter method.

diff --git a/test/testdata/misc.html b/test/testdata/misc.html index adf6398e..2ed1fb1b 100644 --- a/test/testdata/misc.html +++ b/test/testdata/misc.html @@ -1133,26 +1133,40 @@

-
+ +
qux - + +
- + 
135    @property
+136    def qux(self):
+137        return
+
+ +

qux

-
+ +
quux - + +
- + 
139    @cached_property
+140    def quux(self):
+141        return
+
+ +

quux