improving_docs

README.rst

@@ -85,51 +85,47 @@ Basics
 
 Of course, you must import the library to use it:
 
-.. code:: python
+.. code:: python3
 
-    import busio
     import adafruit_ds3231
     import time
 
 All the Adafruit RTC libraries take an instantiated and active I2C object
-(from the ``busio`` library) as an argument to their constructor. The way to
+(from the ``board`` library) as an argument to their constructor. The way to
 create an I2C object depends on the board you are using. For boards with labeled
 SCL and SDA pins, you can:
 
-.. code:: python
+.. code:: python3
 
-    from board import *
-
-You can also use pins defined by the onboard ``microcontroller`` through the
-``microcontroller.pin`` module.
+    import board
 
 Now, to initialize the I2C bus:
 
-.. code:: python
+.. code:: python3
 
-    myI2C = busio.I2C(SCL, SDA)
+    i2c = board.I2C()
 
 Once you have created the I2C interface object, you can use it to instantiate
 the RTC object:
 
-.. code:: python
+.. code:: python3
 
-    rtc = adafruit_ds3231.DS3231(myI2C)
+    rtc = adafruit_ds3231.DS3231(i2c)
 
 Date and time
 -------------
 
 To set the time, you need to set ``datetime`` to a ``time.struct_time`` object:
 
-.. code:: python
+.. code:: python3
 
     rtc.datetime = time.struct_time((2017,1,9,15,6,0,0,9,-1))
 
 After the RTC is set, you retrieve the time by reading the ``datetime``
 attribute and access the standard attributes of a struct_time such as ``tm_year``,
 ``tm_hour`` and ``tm_min``.
 
-.. code:: python
+.. code:: python3
 
     t = rtc.datetime
     print(t)
@@ -141,15 +137,15 @@ Alarm
 To set the time, you need to set ``alarm1`` or ``alarm2`` to a tuple with a
 ``time.struct_time`` object and string representing the frequency such as "hourly":
 
-.. code:: python
+.. code:: python3
 
     rtc.alarm1 = (time.struct_time((2017,1,9,15,6,0,0,9,-1)), "daily")
 
 After the RTC is set, you retrieve the alarm status by reading the corresponding
 ``alarm1_status`` or ``alarm2_status`` attributes. Once True, set it back to False
 to reset.
 
-.. code:: python
+.. code:: python3
 
     if rtc.alarm1_status:
         print("wake up!")

adafruit_ds3231.py

@@ -4,7 +4,7 @@
 # SPDX-License-Identifier: MIT
 
 """
-`adafruit_ds3231` - DS3231 Real Time Clock module
+`adafruit_ds3231`
 =================================================
 CircuitPython library to support DS3231 Real Time Clock (RTC).
 
@@ -26,12 +26,14 @@
 
 **Software and Dependencies:**
 
-* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
-  https://github.com/adafruit/circuitpython/releases
+* Adafruit CircuitPython firmware for the supported boards:
+  https://circuitpython.org/downloads
 
 * Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
+
 * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
 
+
 **Notes:**
 
 #. Milliseconds are not supported by this RTC.
@@ -49,7 +51,42 @@
 
 # pylint: disable-msg=too-few-public-methods
 class DS3231:
-    """Interface to the DS3231 RTC."""
+    """Interface to the DS3231 RTC.
+
+    :param ~busio.I2C i2c: The I2C bus the device is connected to
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`DS3231` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import time
+            import board
+            import adafruit_ds3231
+
+        Once this is done you can define your `board.I2C` object and define your sensor object
+
+        .. code-block:: python
+
+            i2c = board.I2C()  # uses board.SCL and board.SDA
+            rtc = adafruit_ds3231.DS3231(i2c)
+
+        Now you can give the current time to the device.
+
+        .. code-block:: python
+
+            t = time.struct_time((2017, 10, 29, 15, 14, 15, 0, -1, -1))
+            rtc.datetime = t
+
+        You can access the current time accessing the :attr:`datetime` attribute.
+
+        .. code-block:: python
+
+            current_time = rtc.datetime
+
+    """
 
     lost_power = i2c_bit.RWBit(0x0F, 7)
     """True if the device has lost power since the time was set."""

docs/index.rst

@@ -23,6 +23,8 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    Adafruit DS3231 Precision RTC Breakout Learning Guide <https://learn.adafruit.com/adafruit-ds3231-precision-rtc-breakout/>
+
 .. toctree::
     :caption: Related Products
 

examples/ds3231_simpletest.py

@@ -8,20 +8,9 @@
 
 import time
 import board
-
-# For hardware I2C (M0 boards) use this line:
-import busio as io
-
-# Or for software I2C (ESP8266) use this line instead:
-# import bitbangio as io
-
 import adafruit_ds3231
 
-
-i2c = io.I2C(board.SCL, board.SDA)  # Change to the appropriate I2C clock & data
-# pins here!
-
-# Create the RTC instance:
+i2c = board.I2C()  # uses board.SCL and board.SDA
 rtc = adafruit_ds3231.DS3231(i2c)
 
 # Lookup table for names of days (nicer printing).