Updated docs

docs/comparison-qrcode-libs.rst

@@ -60,7 +60,7 @@ Create a QR Code
 
 Create a 1-M QR Code "QR Code Symbol".
 
-.. image:: https://cdn.rawgit.com/heuer/segno/master/sandbox/out/chart_create.svg
+.. image:: _static/chart_create.svg
     :alt: Chart showing the results of creating a 1-M QR Code.
 
 
@@ -70,7 +70,7 @@ Create a QR Code and serialize it as SVG
 Create a QR Code 1-M "QR Code Symbol" and serialize it as SVG document.
 
 
-.. image:: https://cdn.rawgit.com/heuer/segno/master/sandbox/out/chart_svg.svg
+.. image:: _static/chart_svg.svg
     :alt: Chart showing the results of creating a 1-M QR Code and export it as SVG image.
 
 
@@ -80,7 +80,7 @@ Create a QR Code and serialize it as PNG
 
 Create a QR Code 1-M "QR Code Symbol" and serialize it as PNG image.
 
-.. image:: https://cdn.rawgit.com/heuer/segno/master/sandbox/out/chart_png.svg
+.. image::static/chart_png.svg
     :alt: Chart showing the results of creating a 1-M QR Code and export it as SVG image.
 
 

docs/conf.py

@@ -26,12 +26,15 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
     #'sphinx.ext.todo',
     #'sphinx.ext.viewcode',
 ]
 
 autodoc_member_order = 'groupwise'
 
+intersphinx_mapping = {'python': ('https://docs.python.org/2', None)}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/index.rst

@@ -16,6 +16,7 @@ Contents:
    serializers
    comparison-qrcode-libs
    replace-qrcode-libs
+   plugins
    api
 
 

docs/plugins.rst

@@ -0,0 +1,87 @@
+Writing plugins for Segno
+=========================
+
+:py:class:`segno.QRCode` provides a plugin architecture which utilizes egg
+entry points.
+
+All plugins must use the ``segno.plugin.converter`` entry point to be recognized.
+If a plugin is detected, the user may use the the plugin by calling ``to_XXX``
+where ``XXX`` refers to the plugin name.
+
+The specific plugin is invoked by providing the :py:class:`segno.QRCode`
+instance and any further arguments or keywords.
+
+
+Simple plugin
+-------------
+
+This section explains how to write a plugin which writes to ``stdout`` and uses
+``X`` for dark modules and ``_`` for light modules.
+
+Content of ``simple_plugin.py``:
+
+.. code-block:: python
+
+    import sys
+
+    def write(qrcode):
+        write = sys.stdout.write
+        for row in qrcode.matrix:
+            for col in row:
+                write('X' if col else '_')
+            write('\n')
+
+
+``setup.py``:
+
+.. code-block:: python
+
+    setup(
+        name='simple-plugin',
+        version='1.0',
+        license='BSD',
+        author='John Doe',
+        author_email='john@example.org',
+        platforms=['any'],
+        py_modules=['simple_plugin'],
+        entry_points="""
+        [segno.plugin.converter]
+        simple = simple_plugin:write
+        """,
+        install_requires=['segno'],
+    )
+
+Once installed, it's possible to call this plugin via:
+
+.. code-block:: python
+
+    >>> import segno
+    >>> qr = segno.make('Chelsea Hotel No. 2')
+    >>> qr.to_simple()
+    XXXXXXX_XXXX_XX_X_XXXXXXX
+    X_____X___________X_____X
+    X_XXX_X_XX__XXX___X_XXX_X
+    X_XXX_X__X_XXX_X__X_XXX_X
+    X_XXX_X__XX_XX__X_X_XXX_X
+    X_____X_X__XXX__X_X_____X
+    XXXXXXX_X_X_X_X_X_XXXXXXX
+    __________X_X__XX________
+    X_X___XX__XXXXX_X__X__X_X
+    _XX__X_XXXXXX__XX_XX_X__X
+    _X____X____X_XXXX__XX_X_X
+    _XX__X_XX_XXX__XXXX_XX___
+    __X_XXXX_XXX_XX_X_XXXX_X_
+    _____X_X_X___X__XXXX_XX_X
+    XXXXX_X_X_XX___XX_XXXXX_X
+    ____XX__XXX__X_______X_XX
+    XX_X__X__XXXXX_XXXXXX__XX
+    ________X_X_X___X___X____
+    XXXXXXX_X___XXX_X_X_X___X
+    X_____X__X_XX_X_X___XX_XX
+    X_XXX_X___X__XXXXXXXXX_XX
+    X_XXX_X______XX__X__XX_X_
+    X_XXX_X_XXXX_____X_XX_XXX
+    X_____X___X__X__XX_X_X___
+    XXXXXXX_XXXXXX__X_XXXX__X
+
+

docs/serializers.rst

@@ -4,25 +4,16 @@ QR Code and Micro QR Code serialization
 A QR Code or Micro QR Code is independent of its output, it's just a matrix.
 To save a QR Code or Micro QR Code, Segno provides several output formats.
 
-The simpliest way to generate and save a QR Code or Micro QR Code is calling
-
-.. code-block:: python
-
-    >>> import segno
-    >>> # Save as SVG
-    >>> segno.make('Polly').save('polly.svg')
-    >>> # Save as PNG
-    >>> segno.make('Polly').save('polly.png')
-
-
-The above statement are equivalent to
+Segno provides a :py:func:`segno.QRCode.save` method to serialize the (Micro)
+QR Code in different formats:
 
 .. code-block:: python
 
     >>> import segno
     >>> qr = segno.make('Polly')
     >>> qr.save('polly.svg')
     >>> qr.save('polly.png')
+    >>> qr.save('polly.eps')
 
 
 All serializers accept a ``border`` parameter which indicates the "quiet zone"
@@ -40,7 +31,7 @@ a custom border, you may specify the border
 
 Most serializers accept a ``scale`` parameter which indicates the scaling
 factor of the serialization. By default, the scaling factor is ``1`` which means
-that the dark / light modules of a (Micro) QR Code is interpreted as 1 unit in
+that the dark / light modules of a (Micro) QR Code is interpreted as one unit in
 the specific user space (i.e. 1 pixel for the PNG serializer or 1 point (1/72 of
 an inch) in EPS). Some serializers (like PNG) accept only an integer value or
 convert the provided scaling factor to an integer. Other, like SVG and EPS,
@@ -80,4 +71,4 @@ for details.
 
 
 See :py:meth:`segno.QRCode.save` for a complete reference which parameters are
-accepted by the specific serializers.
+accepted by the specific serializer.