improving_docs

README.rst

@@ -72,51 +72,47 @@ Basics
 
 Of course, you must import the library to use it:
 
-.. code:: python
+.. code:: python3
 
-    import busio
-    import adafruit_pcf8523
     import time
+    import adafruit_pcf8523
 
 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 *
+.. code:: python3
 
-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
 
-    i2c_bus = 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_pcf8523.PCF8523(i2c_bus)
+    rtc = adafruit_pcf8523.PCF8523(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)
@@ -128,14 +124,14 @@ Alarm
 To set the time, you need to set `alarm` to a tuple with a `time.struct_time`
 object and string representing the frequency such as "hourly":
 
-.. code:: python
+.. code:: python3
 
     rtc.alarm = (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
 `alarm_status` attribute. Once True, set it back to False to reset.
 
-.. code:: python
+.. code:: python3
 
     if rtc.alarm_status:
         print("wake up!")

adafruit_pcf8523.py

@@ -29,8 +29,11 @@ class is inherited by the chip-specific subclasses.
 
 **Software and Dependencies:**
 
-* Adafruit CircuitPython firmware: 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:**
@@ -54,7 +57,42 @@ class is inherited by the chip-specific subclasses.
 
 
 class PCF8523:
-    """Interface to the PCF8523 RTC."""
+    """Interface to the PCF8523 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:`PCF8523` class.
+        First you will need to import the libraries to use the sensor
+
+        .. code-block:: python
+
+            import time
+            import board
+            import adafruit_pcf8523
+
+        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_pcf8523.PCF8523(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(0x03, 7)
     """True if the device has lost power since the time was set."""

docs/index.rst

@@ -23,8 +23,8 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
-    Adafruit PCF8523 Real Time Clock <https://learn.adafruit.com/adafruit-pcf8523-real-time-clock?view=all>
-    Adafruit Adalogger FeatherWing <https://learn.adafruit.com/adafruit-adalogger-featherwing?view=all>
+    Adafruit PCF8523 Real Time Clock <https://learn.adafruit.com/adafruit-pcf8523-real-time-clock/>
+    Adafruit Adalogger FeatherWing <https://learn.adafruit.com/adafruit-adalogger-featherwing>
 
 .. toctree::
     :caption: Related Products

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