make descriptor usage compatibel with Sphinx autodoc

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

docs/conf.py

@@ -97,3 +97,32 @@
 
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
+
+
+TYPE_MAP = {
+    "DateTime": "datetime",
+    "OptionalDateTime": "Optional[datetime]",
+    "UserProperty": "User",
+}
+
+
+def hook(_app, what, _name, obj, _options, _lines):
+    if what != "class":
+        return
+
+    update = {}
+    for cls in reversed(obj.mro()):
+        annotations = getattr(cls, "__annotations__", {})
+        update.update(
+            {
+                key: TYPE_MAP[value]
+                for key, value in annotations.items()
+                if value in TYPE_MAP
+            }
+        )
+        if obj is cls:
+            annotations.update(update)
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", hook)

zammadoo/articles.py

@@ -163,11 +163,11 @@ class Article(Resource):
     time_unit: Optional[str]  #:
     to: Optional[str]  #:
 
-    created_at = DateTime()
-    created_by = UserProperty()
-    origin_by = UserProperty()
-    updated_at = DateTime()
-    updated_by = UserProperty()
+    created_at: "DateTime" = DateTime()
+    created_by: "UserProperty" = UserProperty()
+    origin_by: "UserProperty" = UserProperty()
+    updated_at: "DateTime" = DateTime()
+    updated_by: "UserProperty" = UserProperty()
 
     @property
     def from_(self) -> str:

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)
 
 
@@ -80,10 +80,10 @@ def __get__(self, instance: Resource, owner=None) -> "User":
 
 
 class MutableResource(Resource):
-    created_at = DateTime()
-    created_by = UserProperty()
-    updated_at = DateTime()
-    updated_by = UserProperty()
+    created_at: "DateTime" = DateTime()
+    created_by: "UserProperty" = UserProperty()
+    updated_at: "DateTime" = DateTime()
+    updated_by: "UserProperty" = UserProperty()
 
     def update(self: _T_co, **kwargs) -> _T_co:
         """

zammadoo/tickets.py

@@ -101,22 +101,22 @@ class Ticket(MutableResource):
     time_unit: Optional[str]  #:
     title: str  #:
 
-    close_at = OptionalDateTime()
-    close_escalation_at = OptionalDateTime()
-    customer = UserProperty()
-    escalation_at = OptionalDateTime()
-    first_response_at = OptionalDateTime()
-    first_response_escalation_at = OptionalDateTime()
-    last_contact_agent_at = OptionalDateTime()
-    last_contact_at = OptionalDateTime()
-    last_contact_customer_at = OptionalDateTime()
-    last_owner_update_at = OptionalDateTime()
+    close_at: "OptionalDateTime" = OptionalDateTime()
+    close_escalation_at: "OptionalDateTime" = OptionalDateTime()
+    customer: "UserProperty" = UserProperty()
+    escalation_at: "OptionalDateTime" = OptionalDateTime()
+    first_response_at: "OptionalDateTime" = OptionalDateTime()
+    first_response_escalation_at: "OptionalDateTime" = OptionalDateTime()
+    last_contact_agent_at: "OptionalDateTime" = OptionalDateTime()
+    last_contact_at: "OptionalDateTime" = OptionalDateTime()
+    last_contact_customer_at: "OptionalDateTime" = OptionalDateTime()
+    last_owner_update_at: "OptionalDateTime" = OptionalDateTime()
     #:
     #:  .. note::
     #:     unassigned tickets will be represented by User with id=1
     #:
-    owner = UserProperty()
-    update_escalation_at = OptionalDateTime()
+    owner: "UserProperty" = UserProperty()
+    update_escalation_at: "OptionalDateTime" = OptionalDateTime()
 
     @property
     def group(self) -> "Group":

zammadoo/time_accountings.py

@@ -73,7 +73,7 @@ class TimeAccounting(MutableResource):
     ticket_article_id: Optional[int]  #:
     time_unit: str  #:
 
-    updated_by = UserProperty("created_by_id")
+    updated_by: "UserProperty" = UserProperty("created_by_id")
 
     @property
     def ticket(self) -> "Ticket":

zammadoo/users.py

@@ -22,20 +22,19 @@ class User(NamedResource):
     fax: str  #:
     firstname: str  #:
     image: Optional[str]  #:
+    last_login: "OptionalDateTime" = 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" = OptionalDateTime()
+    out_of_office_start_at: "OptionalDateTime" = OptionalDateTime()
     phone: str  #:
     verified: bool  #:
     vip: bool  #:
     web: str  #:
 
-    last_login = OptionalDateTime()
-
     @property
     def fullname(self) -> str:
         """users firstname and lastname combined, or email"""