From 9f358595ba7773b8c8e51bd82f25cc9fea29e8e6 Mon Sep 17 00:00:00 2001
From: Panos Mavrogiorgos <pmav99@gmail.com>
Date: Wed, 26 Jul 2023 10:32:01 +0300
Subject: [PATCH] docs: Improve documention of `resolve_timestamps()`

---
 docs/source/index.rst |  1 +
 docs/source/utils.rst |  4 ++++
 searvey/utils.py      | 21 +++++++++++++++------
 3 files changed, 20 insertions(+), 6 deletions(-)
 create mode 100644 docs/source/utils.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index e72313a..b9ffdf7 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,6 +6,7 @@
    coops
    ioc
    usgs
+   utils
 
 `searvey`
 ~~~~~~~~~
diff --git a/docs/source/utils.rst b/docs/source/utils.rst
new file mode 100644
index 0000000..cc847d2
--- /dev/null
+++ b/docs/source/utils.rst
@@ -0,0 +1,4 @@
+utils
+=====
+
+.. autofunction:: searvey.utils.resolve_timestamp
diff --git a/searvey/utils.py b/searvey/utils.py
index 9fc2efe..9631534 100644
--- a/searvey/utils.py
+++ b/searvey/utils.py
@@ -42,23 +42,32 @@ def resolve_timestamp(
     timestamp: DateTimeLike, timezone: str = "utc", timezone_aware: bool = True
 ) -> pd.Timestamp:
     """
-    Parse the provided timestamp and return a `pd.Timestamp` at the specified `timezone`.
+    Parse the provided timestamp and return a ``pd.Timestamp`` at the specified ``timezone``.
 
-    If `timezone_aware` is True, then a timezone-aware Timestamp is returned.
+    If ``"now"`` is passed for the ``timestamp``, then the current timestamp is being returned.
+
+    If ``timezone_aware`` is True, then a timezone-aware Timestamp is returned.
     If not, the function returns a naive Timestamp.
 
-    If `timestamp` contains timezone information (e.g. `2023-05-01T12:12:12+03:30`) then the timestamp is
-    converted to `timezone` before being returned. Do notice that if `timezone_aware` is False,
-    the function still returns a naive Timestamp. For example:
+    If ``timestamp`` contains timezone information (e.g. ``2023-05-01T12:12:12+03:30``) then the timestamp is
+    converted to ``timezone`` before being returned. Do notice that if ``timezone_aware`` is False,
+    the function still returns a naive Timestamp. Some examples will make this clearer:
+
+    A timezone-aware timestamp is converted to the default timezone, i.e. `UTC`:
 
     >>> resolve_timestamp("2001-12-28T12:12:12+0100")
     Timestamp('2001-12-28 11:12:12+0000', tz='UTC')
+
+    A timezone-aware timestamp is converted to the specified timezone:
+
     >>> resolve_timestamp("2001-12-28T12:12:12+0100", timezone="Asia/Tehran")
     Timestamp('2001-12-28 14:42:12+0330', tz='Asia/Tehran')
+
+    A timezone-aware timestamp is converted to the specified timezone but a naive Timestamp is being returned
+
     >>> resolve_timestamp("2001-12-28T12:12:12+0100", timezone="Asia/Tehran", timezone_aware=False)
     Timestamp('2001-12-28 14:42:12')
 
-    If `"now"` is passed for the `timestamp`, then the current timestamp is being returned.
     """
     if str(timestamp).lower() == NOW:
         ts = pd.Timestamp.now(tz=timezone)