Improved documentation of PIconnect.time module

PIconnect/time.py

@@ -1,20 +1,27 @@
 from datetime import datetime
+
 import pytz
 
 from PIconnect.AFSDK import AF
 from PIconnect.config import PIConfig
 
 
 def to_af_time_range(start_time, end_time):
-    """to_af_time_range
+    """Convert a combination of start and end time to a time range.
 
-    Return AF.Time.AFTimeRange object from datetime or string
-    using :afsdk:`AF.Time.AFTimeRange <M_OSIsoft_AF_Time_AFTimeRange__ctor_1.htm>`.
+    Both `start_time` and `end_time` can be either a :any:`datetime.datetime` object or a string.
+    `datetime` objects are first converted to a string, before being passed to
+    :afsdk:`AF.Time.AFTimeRange <M_OSIsoft_AF_Time_AFTimeRange__ctor_1.htm>`. It is also
+    possible to specify either end as a `datetime` object, and then specify the other
+    boundary as a relative string.
 
-    If string is used, it is assumed that user knows the format
-    that should be passed to AF.Time.AFTimeRange.
-    """
+    Args:
+        start_time (str | datetime): Start time of the time range.
+        end_time (str | datetime): End time of the time range.
 
+    Returns:
+        :afsdk:`AF.Time.AFTimeRange <M_OSIsoft_AF_Time_AFTimeRange__ctor_1.htm>`: Time range covered by the start and end time.
+    """
     if isinstance(start_time, datetime):
         start_time = start_time.isoformat()
     if isinstance(end_time, datetime):
@@ -26,12 +33,11 @@ def to_af_time_range(start_time, end_time):
 def timestamp_to_index(timestamp):
     """Convert AFTime object to datetime in local timezone.
 
-    .. todo::
-
-        Allow to define timezone, default to UTC?
-
-    .. todo::
+    Args:
+        timestamp (`System.DateTime`): Timestamp in .NET format to convert to `datetime`.
 
+    Returns:
+        `datetime`: Datetime with the timezone info from :data:`PIConfig.DEFAULT_TIMEZONE <PIconnect.config.PIConfigContainer.DEFAULT_TIMEZONE>`.
     """
     local_tz = pytz.timezone(PIConfig.DEFAULT_TIMEZONE)
     return (

docs/conf.py

@@ -94,6 +94,7 @@ def __getattr__(cls, name):
 }
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.8", None),
     "pandas": ("https://pandas.pydata.org/docs", None),
     "pytz": ("http://pytz.sourceforge.net", None),
 }