improving_docs

README.rst

@@ -72,36 +72,33 @@ Usage Notes
 
 Of course, you must import the library to use it:
 
-.. code:: python
+.. code:: python3
 
-    import busio
+    import board
     import adafruit_ds1307
     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
 
-    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
 
-    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
 
-    rtc = adafruit_ds1307.DS1307(myI2C)
+    rtc = adafruit_ds1307.DS1307(i2c)
 
 To set the time, you need to set ``datetime`` to a `time.struct_time` object:
 

adafruit_ds1307.py

@@ -27,9 +27,11 @@
 
 **Software and Dependencies:**
 
-* Adafruit CircuitPython firmware (0.8.0+) 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:**
@@ -49,7 +51,42 @@
 
 
 class DS1307:
-    """Interface to the DS1307 RTC."""
+    """Interface to the DS1307 RTC.
+
+    :param ~busio.I2C i2c_bus: The I2C bus the device is connected to
+
+    **Quickstart: Importing and using the device**
+
+        Here is an example of using the :class:`DS1307` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import time
+            import board
+            import adafruit_ds1307
+
+        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_ds1307.DS1307(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
+
+    """
 
     disable_oscillator = i2c_bit.RWBit(0x0, 7)
     """True if the oscillator is disabled."""

docs/index.rst

@@ -23,6 +23,8 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
+    Adafruit DS1307 Real Time Clock Assembled Breakout Board Learning Guide <https://learn.adafruit.com/ds1307-real-time-clock-breakout-board-kit>
+
 .. toctree::
     :caption: Related Products
 

examples/ds1307_simpletest.py

@@ -8,20 +8,10 @@
 
 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_ds1307
 
-# Change to the appropriate I2C clock & data pins here!
-i2c_bus = io.I2C(board.SCL, board.SDA)
-
-# Create the RTC instance:
-rtc = adafruit_ds1307.DS1307(i2c_bus)
+i2c = board.I2C()
+rtc = adafruit_ds1307.DS1307(i2c)
 
 # Lookup table for names of days (nicer printing).
 days = ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday")