beautiful API desciption

BoboTiG · BoboTiG · commit 0aa861f45fdb · 2016-05-02T09:40:14.000+02:00
diff --git a/README.md b/README.md
@@ -144,57 +144,96 @@ A screenshot to grab them all:
 print(next(screenshotter.save(mon=-1, output='fullscreen.png')))
 ```
 
-
-API: version 2
-==============
+Example into the Python's console
+---
 
 ```python
-enum_display_monitors(force=False)
+>>> from mss import mss
+>>> sct = mss(display=b':0')
+
+# Retrieve monitors informations
+>>> displays = sct.enum_display_monitors()
+>>> displays
+[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]
+# You can access monitors list via `monitors`:
+>>> sct.monitors
+[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]
+
+# Retrieve pixels from the first monitor
+>>> pixels = sct.get_pixels(displays[1])
+>>> pixels
+<ctypes.c_char_Array_6220800 object at 0x7fe82e9007a0>
+# You can access pixels data via `image`:
+>>> sct.image
+<ctypes.c_char_Array_6220800 object at 0x7fe82e9007a0>
+
+# Save pixels to a PNG file: option 1
+>>> files = sct.save(mon=1)
+>>> next(files)
+'monitor-1.png'
+>>> next(files)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+StopIteration
+
+# Save pixels to a PNG file: option 2
+>>> mon = displays[1]
+>>> sct.to_png(data=pixels, width=mon[b'width'], height=mon[b'height'], output='monitor-1.png')
 ```
 
-Get positions and dimensions of monitors. If `force` is set to `True`, it will rescan for monitors informations.
+---
 
-It stocks monitors informations into `monitors` and returns it.
+API
+===
 
----
+**enum_display_monitors** => list of dicts
 
 ```python
-get_pixels(monitor)
+>>> enum_display_monitors(force=False)
+''' Get positions and dimensions of monitors.
+    If `force` is set to `True`, it will rescan for monitors informations.
+    It stocks monitors informations into `monitors` and returns it.
+    `monitors[0]` is a dict of all monitors together
+    `monitors[N]` is a dict of the monitor N (with N > 0)
+'''
 ```
 
-Retrieve screen pixels for a given monitor. `monitor` is a dict generated by `enum_display_monitors()`.
+**get_pixels** => array of ctypes.c_char
 
-It stocks pixels data into `image` (RGB) and returns it.
+```python
+>>> get_pixels(monitor)
+''' Retrieve screen pixels for a given monitor.
+    `monitor` is a dict generated by `enum_display_monitors()`.
+    It stocks pixels data into `image` (RGB) and returns it.
+'''
+```
 
----
+**save** => generator
 
 ```python
-save(mon=0, output='monitor-%d', callback=lambda *x: True)
-```
+>>> save(mon=0, output='monitor-%d', callback=lambda *x: True)
+''' Grab a screenshot and save it to a file.
 
-Grab a screenshot and save it to a file. Parameters:
+    `mon` is an integer:
+        -1: grab one screenshot of all monitors
+         0: grab one screenshot by monitor
+         N: grab the screenshot of the monitor N
 
-```
-mon
-    -1: grab one screenshot of all monitors
-     0: grab one screenshot by monitor
-     N: grab the screenshot of the monitor N
-
-output
-    The output filename.
-    %d, if presents, will be replaced by the monitor number.
-
-callback
-    Callback called before saving the screenshot to a file.
-    Take the 'output' argument as parameter.
-```
+    `output` is a string:
+        The output filename.
+        %d, if presents, will be replaced by the monitor number.
 
-This is a generator which returns created files.
+    `callback` is a method:
+        Callback called before saving the screenshot to a file.
+        Takes `output` argument as parameter.
 
----
+    This is a generator which returns created files.
+'''
+```
+
+**to_png**
 
 ```python
-to_png(data, width, height, output)
+>>> to_png(data, width, height, output)
+''' Dump raw `data` into PNG `output` file. '''
 ```
-
-Dump raw `data` into `output` file.
