Improved documentation

inkycal/display/display.py

@@ -12,7 +12,15 @@ import glob
 
 class Display:
   """Display class for inkycal
-  Handles rendering on display"""
+
+  Creates an instance of the driver for the selected E-Paper model and allows
+  rendering images and calibrating the E-Paper display
+
+  args:
+    - epaper_model: The name of your E-Paper model.
+
+  
+  """
 
   def __init__(self, epaper_model):
     """Load the drivers for this epaper model"""
@@ -35,8 +43,41 @@ class Display:
       raise Exception('SPI could not be found. Please check if SPI is enabled')
 
   def render(self, im_black, im_colour = None):
-    """Render an image on the epaper
-    im_colour is required for three-colour epapers"""
+    """Renders an image on the selected E-Paper display.
+
+    Initlializes the E-Paper display, sends image data and executes command
+    to update the display.
+
+    Args:
+      - im_black: The image for the black-pixels. Anything in this image that is
+        black is rendered as black on the display. This is required and ideally
+        should be a black-white image.
+
+      - im_colour: For E-Paper displays supporting colour, a separate image,
+        ideally black-white is required for the coloured pixels. Anything that is
+        black in this image will show up as either red/yellow.
+
+    Rendering an image for black-white E-Paper displays:
+    
+    >>> sample_image = PIL.Image.open('path/to/file.png')
+    >>> display = Display('my_black_white_display')
+    >>> display.render(sample_image)
+
+
+    Rendering black-white on coloured E-Paper displays:
+    
+    >>> sample_image = PIL.Image.open('path/to/file.png')
+    >>> display = Display('my_coloured_display')
+    >>> display.render(sample_image, sample_image)
+
+
+    Rendering coloured image where 2 images are available:
+
+    >>> black_image = PIL.Image.open('path/to/file.png') # black pixels
+    >>> colour_image = PIL.Image.open('path/to/file.png') # coloured pixels
+    >>> display = Display('my_coloured_display')
+    >>> display.render(black_image, colour_image)
+    """
 
     epaper = self._epaper
 
@@ -65,9 +106,23 @@ class Display:
     print('Done')
 
   def calibrate(self, cycles=3):
-    """Flush display with single colour to prevent burn-ins (ghosting)
-    cycles -> int. How many times should each colour be flushed?
-    recommended cycles = 3"""
+    """Calibrates the display to retain crisp colours
+
+    Flushes the selected display several times with it's supported colours,
+    removing any previous effects of ghosting.
+
+    Args:
+      - cycles: -> int. The number of times to flush the display with it's
+        supported colours.
+
+    It's recommended to calibrate the display after every 6 display updates
+    for best results. For black-white only displays, calibration is less
+    critical, but not calibrating regularly results in grey-ish text.
+
+    Please note that calibration takes a while to complete. 3 cycles may
+    take 10 mins on black-white E-Papers while it takes 20 minutes on coloured
+    E-Paper displays.
+    """
 
     epaper = self._epaper
     epaper.init()
@@ -102,7 +157,21 @@ class Display:
 
   @classmethod
   def get_display_size(cls, model_name):
-    "returns (width, height) of given display"
+    """Returns the size of the display as a tuple -> (width, height)
+
+    Looks inside drivers folder for the given model name, then returns it's
+    size.
+
+    Args:
+      - model_name: str -> The name of the E-Paper display to get it's size.
+
+    Returns:
+      (width, height) ->tuple, showing the size of the display
+
+    You can use this function directly without creating the Display class:
+
+    >>> Display.get_display_size('model_name')
+    """
     if not isinstance(model_name, str):
       print('model_name should be a string')
       return
@@ -110,6 +179,8 @@ class Display:
       driver_files = top_level+'/inkycal/display/drivers/*.py'
       drivers = glob.glob(driver_files)
       drivers = [i.split('/')[-1].split('.')[0] for i in drivers]
+      drivers.remove('__init__')
+      drivers.remove('epdconfig')
       if model_name not in drivers:
         print('This model name was not found. Please double check your spellings')
         return
@@ -122,6 +193,28 @@ class Display:
               height = int(line.rstrip().replace(" ", "").split('=')[-1])
         return width, height
 
+  @classmethod
+  def get_display_names(cls):
+    """Prints all supported E-Paper models.
+
+    Fetches all filenames in driver folder and prints them on the console.
+
+    Returns:
+      Printed version of all supported Displays.
+
+    Use one of the models to intilialize the Display class in order to gain
+    access to the E-Paper.
+
+    You can use this function directly without creating the Display class:
+    
+    >>> Display.get_display_names()
+    """
+    driver_files = top_level+'/inkycal/display/drivers/*.py'
+    drivers = glob.glob(driver_files)
+    drivers = [i.split('/')[-1].split('.')[0] for i in drivers]
+    drivers.remove('__init__')
+    drivers.remove('epdconfig')
+    print(*drivers, sep='\n')
             
 if __name__ == '__main__':
   print("Running Display class in standalone mode")