update docs of DS1307

Author: brainelectronics

docs/DOCUMENTATION.md

@@ -8,7 +8,7 @@ Documentation is generated by using Sphinx and published on RTD
 
 Documentation is automatically created on each merge to the development
 branch, as well as with each pull request and available
-[📚 here at Read the Docs][ref-rtd-micropython-package-template]
+[📚 here at Read the Docs][ref-rtd-micropython-ds1307]
 
 ### Install required packages
 
@@ -37,4 +37,4 @@ sphinx-build docs/ docs/build/html/ -d docs/build/docs_doctree/ --color -bhtml -
 The created documentation can be found at `docs/build/html`.
 
 <!-- Links -->
-[ref-rtd-micropython-package-template]: https://micropython-package-template.readthedocs.io/en/latest/
+[ref-rtd-micropython-ds1307]: https://micropython-ds1307.readthedocs.io/en/latest/

docs/EXAMPLES.md

@@ -1,28 +1,110 @@
 # Examples
 
-Usage examples of this `micropython-package-template` library
+Usage examples of this `micropython-ds1307` library
 
 ---------------
 
-## TBD
+## General
 
-Some text with *italic*, **bold** and `hightlighted` words.
+An example of all implemented functionalities can be found at the
+[MicroPython DS1307 examples folder][ref-micropython-ds1307-examples]
 
-```{note}
-A reStructuredText highlighted note
+## Setup DS1307
+
+```python
+from eeprom import DS1307
+from machine import I2C, Pin
+
+I2C_ADDR = 0x68
+
+# define custom I2C interface, default is 'I2C(0)'
+# check the docs of your device for further details and pin infos
+# this are the pins for the Raspberry Pi Pico adapter board
+i2c = I2C(0, scl=Pin(13), sda=Pin(12), freq=800000)
+ds1307 = DS1307(addr=I2C_ADDR, i2c=i2c)   # DS1307 on 0x68
+
+# get LCD infos/properties
+print("DS1307 is on I2C address 0x{0:02x}".format(ds1307.addr))
+print("Weekday start is {}".format(ds1307.weekday_start))
 ```
 
-```{eval-rst}
-.. warning::
-    Some eval warning
+## Set time
+
+Set the RTC time to the current system time
+
+```python
+from time import gmtime, time
+
+now = gmtime(time())
+ds1307.datetime = now
 ```
 
+## Get time
+
+Get the current RTC time and all available properties of `DS1307`
+
 ```python
-def hello_world():
-    print('Hello')
+# Print the date and time in ISO8601 format: 2023-04-18T21:14:22
+print("Today is {:04d}-{:02d}-{:02d}T{:02d}:{:02d}:{:02d}".format(
+    ds1307.year, ds1307.month, ds1307.day,
+    ds1307.hour, ds1307.minute, ds1307.second))
+
+# check whether this year is a leap year
+print("Is this year a leap year? {}".format(ds1307.is_leap_year(ds1307.year)))
+
+# get the day of the year
+print("Today is day {} of {}".format(
+    ds1307.day_of_year(year=ds1307.year, month=ds1307.month, day=ds1307.day),
+    ds1307.year))
+```
+
+## Oscillator
+
+Interact with the oscillator of the RTC
+
+```python
+from time import sleep
+
+print("The oscillator is currently active at {}? {}".format(
+    ds1307.datetime, ds1307.halt))
+print("Halt the oscillator and wait for 5 seconds ...")
+ds1307.halt = True
+sleep(5)
+
+print("Current RTC time: {}".format(ds1307.datetime))
+
+print("Enable the oscillator and wait for 5 seconds ...")
+ds1307.halt = False
+sleep(5)
+print("Current RTC time: {}".format(ds1307.datetime))
+```
+
+## Square Wave Pin
+
+Control the squarewave pin `SQ`
+
+```python
+from time import sleep
+
+print("Set square wave output to 1Hz and wait for 5 seconds ...")
+ds1307.square_wave(sqw=1)
+sleep(5)
+
+print("Set square wave output to 4.096kHz and wait for 5 seconds ...")
+ds1307.square_wave(sqw=4)
+sleep(5)
+
+print("Set square wave output to 8.192kHz and wait for 5 seconds ...")
+ds1307.square_wave(sqw=8)
+sleep(5)
+
+print("Set square wave output to HIGH and wait for 5 seconds ...")
+ds1307.square_wave(out=1)
+sleep(5)
+
+print("Set square wave output to LOW and wait for 5 seconds ...")
+ds1307.square_wave(sqw=0)
+sleep(5)
 ```
 
-| Type  | Individual | Prefered food |
-| ----- | ---------- | ------------- |
-| Car | E-Power | Electricity |
-| Animal  | Cat | Mice |
+[ref-micropython-ds1307-examples]: https://github.com/brainelectronics/micropython-ds1307/tree/main/examples

docs/conf.py

@@ -21,22 +21,21 @@
     to_be_mocked = [
         'micropython',
         'machine',
-        'time.sleep_ms', 'time.sleep_us',
     ]
     for module in to_be_mocked:
         sys.modules[module] = Mock()
         print("Mocked '{}' module".format(module))
 
-    import be_upy_blink
+    import ds1307
 except ImportError:
-    raise SystemExit("be_upy_blink has to be importable")
+    raise SystemExit("ds1307 has to be importable")
 
 # load elements of version.py
-exec(open(here / '..' / 'be_upy_blink' / 'version.py').read())
+exec(open(here / '..' / 'ds1307' / 'version.py').read())
 
 # -- Project information
 
-project = 'micropython-package-template'
+project = 'micropython-ds1307'
 copyright = '2023, brainelectronics'
 author = 'brainelectronics'
 
@@ -78,10 +77,10 @@
 # A list of regular expressions that match URIs that should not be checked
 # when doing a linkcheck build.
 linkcheck_ignore = [
-    # tag 0.4.0 did not exist during docs introduction
-    'https://github.com/brainelectronics/micropython-package-template/tree/0.4.0',
+    # tag 0.1.0 did not exist during docs introduction
+    'https://github.com/brainelectronics/micropython-ds1307/tree/0.1.0',
     # RTD page did not exist during docs introduction
-    'https://micropython-package-template.readthedocs.io/en/latest/',
+    'https://micropython-ds1307.readthedocs.io/en/latest/',
 ]
 
 templates_path = ['_templates']

docs/ds1307.rst

@@ -0,0 +1,13 @@
+API
+=======================
+
+.. autosummary::
+   :toctree: generated
+
+DS1307
+---------------------------------
+
+.. automodule:: ds1307.ds1307
+   :members:
+   :private-members:
+   :show-inheritance:

docs/index.rst

@@ -1,4 +1,4 @@
-MicroPython package template
+MicroPython DS1307
 ===================================
 
 Contents
@@ -11,7 +11,7 @@ Contents
    EXAMPLES
    DOCUMENTATION
    CONTRIBUTING
-   be_upy_blink
+   ds1307
    changelog_link
 
 Indices and tables