cleanup docstrings for Sphinx and reST

add new example to documentation
remove debug code from example

Author: mMerlin

adafruit_ntp.py

@@ -165,17 +165,23 @@ class NTP:  # pylint:disable=too-many-instance-attributes
 
     This class uses a simple state machine to manage synchronization:
     - USING_CACHED_REFERENCE (state 3): The default state where the cached time reference is used.
-        - Transitions to GETTING_SOCKET when the cache expires.
+
+       - Transitions to GETTING_SOCKET when the cache expires.
+
     - GETTING_SOCKET (state 1): Attempts to perform a DNS lookup for the NTP server.
-        - Transitions to GETTING_PACKET on success.
-        - Remains in this state if retries are needed.
+
+       - Transitions to GETTING_PACKET on success.
+       - Remains in this state if retries are needed.
+
     - GETTING_PACKET (state 2): Sends an NTP request and waits for the response.
-        - Transitions back to USING_CACHED_REFERENCE.
-        - On failure, any existing cached value will continue to be used until the next scheduled
-          synchronization.
 
-    The state transitions are managed by the `_update_time_sync` method, which is called if
-    the cached time is expired when `utc_ns` is accessed.
+       - Transitions back to USING_CACHED_REFERENCE.
+
+    - On failure, any existing cached value will continue to be used until the next scheduled
+      synchronization.
+
+    The state transitions are managed by the ``_update_time_sync`` method, which is called if
+    the cached time is expired when ``utc_ns`` is accessed.
     """
 
     # State machine values
@@ -374,15 +380,15 @@ def register_ntp_event_callback(
 
         Callbacks can be used to turn off the radio to save power, initiate a network
         connection, or other progress monitoring processes.
-        EG: `wifi.radio.enabled = False` or `connection_manager.connect()`
+        EG: ``wifi.radio.enabled = False`` or ``connection_manager.connect()``
 
         .. caution::
 
            This implementation does not prevent duplicate registration of the same callback.
            All attempts to consistently identify when a callback is already registered have
            failed due to the limitations of the current CircuitPython implementation. Comparing
-           the callback value directly, converting to string using `str()`, or `repr()`, or to a
-           number using `id()` all have cases where an identical callback reference will be
+           the callback value directly, converting to string using ``str()``, or ``repr()``, or to a
+           number using ``id()`` all have cases where an identical callback reference will be
            treated as different.
 
            If the same callback is registered multiple times, with the same event type, it will
@@ -391,8 +397,8 @@ def register_ntp_event_callback(
         :param Callable[[IntFlag, int], None] callback: The callback function to register.
         :param IntFlag event_types: The event types that should trigger this callback. This can
                                     be a single event type or a combination of multiple events.
-                                    Defaults to `EventType.SYNC_COMPLETE`.
-        :raises TypeError: If the `event_types` argument is not a valid event type or combination
+                                    Defaults to ``EventType.SYNC_COMPLETE``.
+        :raises TypeError: If the ``event_types`` argument is not a valid event type or combination
                            of event types.
 
         Usage examples::

docs/examples.rst

@@ -8,14 +8,23 @@ Ensure your device works with this simple test that prints out the time from NTP
     :linenos:
 
 Set RTC
-------------
+-------
 
 Sync your CircuitPython board's realtime clock (RTC) with time from NTP.
 
 .. literalinclude:: ../examples/ntp_set_rtc.py
     :caption: examples/ntp_set_rtc.py
     :linenos:
 
+Using Notifications
+-------------------
+
+Using notifications to monitor state and control power usage.
+
+.. literalinclude:: ../examples/ntp_powersave.py
+    :caption: examples/ntp_powersave.py
+    :linenos:
+
 Simple test with CPython
 ------------------------
 

examples/ntp_powersave.py

@@ -22,12 +22,6 @@
 def on_ntp_event(event_type: EventType, next_time: int):
     """Handle notifications from NTP about not using the radio for awhile."""
     global check_connection  # pylint:disable=global-statement
-    if event_type == EventType.NO_EVENT:
-        print(
-            "No Event: "
-            f"{time.monotonic_ns() =}, {wifi.radio.enabled =}, {wifi.radio.connected =}"
-        )
-        return
     print(f"event {event_type}: Next operation scheduled at {next_time} ns")
     if event_type == EventType.LOOKUP_FAILED:
         check_connection = True
@@ -82,9 +76,5 @@ def fmt_iso(datetime: time.struct_time) -> str:
             print(fmt_iso(ntp.datetime))
         except NTPIncompleteError:
             print("Waiting for NTP information")
-        except Exception as ex:
-            print(f"{type(ex)}")
-            print(f"Exception: {ex}")
-            raise
     # other regular processing …
     time.sleep(1)