Usage documentation

svartalf · svartalf · commit d1a3d6ed5803 · 2012-05-23T23:32:13.000+09:00
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1 @@
+quirc
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -90,7 +90,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/docs/source/usage/high-level.rst b/docs/source/usage/high-level.rst
@@ -0,0 +1,26 @@
+High-level API
+==============
+
+It is very simple in use::
+
+    import quirc
+    from PIL import Image
+
+    for code in quirc.decode(Image.open('images/qr-code.png')):
+        print code['text']
+
+`quirc.decode` function returns generator, which contains results of QR codes recognition.
+Each item is `dict` object with those keys:
+
+    corners
+        Tuple with the four corners of the QR code, from top left, clockwise
+    size
+        The number of cells across in the QR code
+    version
+        QR code version
+    ecc_level
+        The percentage of unreadable codewords can be restored in a QR Code symbol without data loss
+    data_type
+        QR code type
+    text
+        Encoded text
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
@@ -1,5 +1,13 @@
 Usage
 =====
 
-.. automodule:: quirc
-   :members:
+Library usage splits into two parts: *high-level* and *low-level* API.
+
+In a sunny and beautiful world you will need only a *high-level* API.
+But if you are have not so much free memory or want to control whole the process, use a *low-level* API.
+
+.. toctree::
+    :maxdepth: 1
+
+    high-level
+    low-level
diff --git a/docs/source/usage/low-level.rst b/docs/source/usage/low-level.rst
@@ -0,0 +1,49 @@
+Low-level API
+==============
+
+Low-level API fully copies the C API and contains all in the `quirc.api` module.
+
+.. automodule:: quirc.api
+
+
+Usage
+-----
+
+::
+
+    from quirc import api
+    from PIL import Image
+
+    image = Image.open('images/qr-code.png')
+    width, height = image.size
+
+    # Convert image to the grayscale mode
+    if not image.mode in ('L', '1'):
+        image = image.convert('L')
+    pixels = image.load()
+
+    obj = api.new()
+    api.resize(obj, width, height)
+
+    buffer = api.begin(obj, width, height)
+
+    # Fill buffer with a image pixels. One cell, one pixel.
+    idx = 0
+    for i in range(width):
+        for j in range(height):
+            buffer[idx] = ctypes.c_uint8(pixels[j, i])
+            idx += 1
+
+    # Finish image recognition
+    api.end(obj)
+
+    code = api.structures.Code()
+    data = api.structures.Data()
+
+    for i in range(api.count(obj)):
+        api.extract(obj, i, code)
+        api.decode(code, data)
+
+        print ctypes.string_at(data.payload, data.payload_len)
+
+    api.destroy(obj)
diff --git a/quirc/base.py b/quirc/base.py
@@ -61,9 +61,8 @@ def decode(image):
             'size': code.size,
             'version': data.version,
             'ecc_level': data.ecc_level,
-            'mask': data.mask,
             'data_type': data.data_type,
             'text': ctypes.string_at(data.payload, data.payload_len),
-            }
+        }
 
     api.destroy(obj)
diff --git a/setup.py b/setup.py
@@ -8,6 +8,12 @@
 
 This library is fast, small, easy to use, have a very small memory usage,
 and optionally requires one of the image processing libraries.
+
+Links
+------
+
+ * `Documentation <http://python-quirc.readthedocs.org>`_
+
 """
 
 from setuptools import setup
diff --git a/tests/test_quirc.py b/tests/test_quirc.py
@@ -34,7 +34,6 @@ def test_pil(self):
         code = result[0]
 
         self.assertEqual(code['data_type'], 4)
-        self.assertEqual(code['mask'], 6)
         self.assertEqual(code['ecc_level'], 0)
         self.assertEqual(code['size'], 29)
 
