make descriptor usage compatibel with Sphinx autodoc

Signed-off-by: flashdagger <flashdagger@googlemail.com>

docs/conf.py

@@ -97,3 +97,36 @@
 
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
+
+dummy_object = object()
+empty_dict = {}
+
+
+def hook(_app, what, _name, obj, _options, _lines):
+    if what != "class":
+        return
+
+    annotations = {}
+    for cls in reversed(obj.mro()):
+        cls_annotations = getattr(cls, "__annotations__", empty_dict)
+
+        for key, value in cls.__dict__.items():
+            if key.startswith("_") or not isinstance(value, object):
+                continue
+
+            if key in cls_annotations:
+                annotations[key] = cls_annotations[key]
+            else:
+                getter = getattr(value, "__get__", dummy_object)
+                return_type = getattr(getter, "__annotations__", empty_dict).get(
+                    "return"
+                )
+                if return_type:
+                    annotations[key] = return_type
+
+        if cls is obj:
+            cls_annotations.update(annotations)
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", hook)

zammadoo/resource.py

@@ -61,7 +61,7 @@ def reload(self, expand=False) -> None:
         info.update(new_info)
 
     def last_request_at(self) -> Optional[datetime]:
-        """return the last request timestamp as :class:`datetime` or ``None``"""
+        """:return: the last request timestamp as :class:`datetime` or ``None``"""
         return self.parent.cached_timestamp(self.id)
 
 

zammadoo/time_accountings.py

@@ -72,7 +72,6 @@ class TimeAccounting(MutableResource):
     ticket_id: int  #:
     ticket_article_id: Optional[int]  #:
     time_unit: str  #:
-
     updated_by = UserProperty("created_by_id")
 
     @property

zammadoo/users.py

@@ -22,20 +22,19 @@ class User(NamedResource):
     fax: str  #:
     firstname: str  #:
     image: Optional[str]  #:
+    last_login = OptionalDateTime()
     lastname: str  #:
     login: str  #: users login name
     login_failed: int  #:
     mobile: str  #:
     out_of_office: bool  #:
-    out_of_office_end_at: Optional[str]  #:
-    out_of_office_start_at: Optional[str]  #:
+    out_of_office_end_at = OptionalDateTime()
+    out_of_office_start_at = OptionalDateTime()
     phone: str  #:
     verified: bool  #:
     vip: bool  #:
     web: str  #:
 
-    last_login = OptionalDateTime()
-
     @property
     def fullname(self) -> str:
         """users firstname and lastname combined, or email"""