Add documentation

Makefile

@@ -1,12 +1,15 @@
-.PHONY: install lint test
+.PHONY: docs install lint test
 
 all: install lint test
 
+docs:
+	sphinx-autobuild -z zxinglight/ docs/ docs/_build/html/
+
 install:
 	pip install -e .[test]
 
 lint:
-	flake8 zxinglight/ tests/ setup.py
+	flake8 zxinglight/ tests/ docs/ setup.py
 
 test:
 	nosetests tests/

README.rst

@@ -1,14 +1,19 @@
-ZxingLight
+ZXingLight
 ==========
 
-|build-status|
+|build-status| |docs-status|
 
-A simple wrapper for zxing-cpp_ inspired by zbarlight_.
+A simple wrapper for `ZXing C++`_ inspired by zbarlight_.
 
-.. _zxing-cpp: https://github.com/glassechidna/zxing-cpp
+Documentation is available on <https://zxinglight.readthedocs.io/en/latest/>.
+
+.. _ZXing C++: https://github.com/glassechidna/zxing-cpp
 .. _zbarlight: https://github.com/Polyconseil/zbarlight
 
 
 .. |build-status| image:: https://travis-ci.org/Lubo/zxinglight.svg?branch=master
     :alt: Build status
     :target: https://travis-ci.org/Lubo/zxinglight
+.. |docs-status| image:: https://readthedocs.org/projects/zxinglight/badge/?version=latest
+    :alt: Documentation status
+    :target: https://zxinglight.readthedocs.io/en/latest/

docs/conf.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# zxinglight documentation build configuration file, created by
+# sphinx-quickstart on Tue Mar  7 09:05:21 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import sys
+
+parent = os.path.dirname(os.path.dirname(__file__))
+sys.path.append(parent)
+
+
+class _Zxinglight:
+    """"Mocks import of _zxinglight"""
+
+    def zxing_read_codes(self, *args):
+        pass
+
+
+sys.modules['zxinglight._zxinglight'] = _Zxinglight
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'pillow': ('https://pillow.readthedocs.io/en/latest', None),
+}
+
+autodoc_member_order = 'bysource'
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'ZXingLight'
+copyright = '2017, Ľubomír Kučera'
+author = 'Ľubomír Kučera'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0.0'
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# 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
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,24 @@
+Welcome to ZXingLight's documentation!
+======================================
+
+ZXingLight is a simple Python wrapper for `ZXing C++`_ inspired by zbarlight_.
+
+.. _ZXing C++: https://github.com/glassechidna/zxing-cpp
+.. _zbarlight: https://github.com/Polyconseil/zbarlight
+
+Table of contents
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation.rst
+   reference.rst
+
+
+.. Indices and tables
+.. ==================
+..
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`

docs/installation.rst

@@ -0,0 +1,39 @@
+Installation
+============
+
+Requirements
+------------
+
+Before installing ZXingLight, you need to:
+
+1. `Install ZXing C++`_
+2. Install C++11 compatible version of g++ (>= 4.8.1)
+
+.. _Install ZXing C++: #installing-zxing-c
+
+Installing ZXing C++
+--------------------
+
+Download and install `ZXing C++`_ according to README_.
+
+.. warning::
+    Do not forget to use :code:`-DCMAKE_CXX_FLAGS=-fPIC`. Otherwise, linking will fail while
+    installing ZXingLight.
+
+.. _ZXing C++: https://github.com/glassechidna/zxing-cpp
+.. _README: https://github.com/glassechidna/zxing-cpp/blob/master/README.md#building-using-cmake
+
+Installing ZXingLight
+---------------------
+
+ZXingLight can be installed from PyPI using pip:
+
+.. code-block:: bash
+
+    $ pip install zxinglight
+
+Or using setuptools:
+
+.. code-block:: bash
+
+    $ python setup.py install

docs/reference.rst

@@ -0,0 +1,5 @@
+Reference
+=========
+
+.. automodule:: zxinglight
+    :members: BarcodeType, read_codes

setup.py

@@ -11,7 +11,7 @@ def read(file_path):
 setup(
     name='zxinglight',
     version='1.0.0',
-    description='A simple zxing-cpp wrapper',
+    description='A simple ZXing C++ wrapper',
     long_description=read('README.rst'),
     classifiers=[
         'Development Status :: 5 - Production/Stable',
@@ -61,6 +61,11 @@ def read(file_path):
         'Pillow'
     ],
     extras_require={
+        'docs': [
+            'Sphinx',
+            'sphinx-autobuild',
+            'sphinx_rtd_theme'
+        ],
         'test': [
             'flake8',
             'nose',

zxinglight/__init__.py

@@ -8,27 +8,83 @@
 
 @unique
 class BarcodeType(IntEnum):
+    """
+    Enumeration of barcode types supported by ZXing.
+    """
+
+    #: Default barcode type. If used, ZXing will read all types of barcodes.
     NONE = 0
+
+    #:
     AZTEC = 1
+
+    #:
     CODABAR = 2
+
+    #:
     CODE_39 = 3
+
+    #:
     CODE_93 = 4
+
+    #:
     CODE_128 = 5
+
+    #:
     DATA_MATRIX = 6
+
+    #:
     EAN_8 = 7
+
+    #:
     EAN_13 = 8
+
+    #:
     ITF = 9
+
+    #:
     MAXICODE = 10
+
+    #:
     PDF_417 = 11
+
+    #:
     QR_CODE = 12
+
+    #:
     RSS_14 = 13
+
+    #:
     RSS_EXPANDED = 14
+
+    #:
     UPC_A = 15
+
+    #:
     UPC_E = 16
+
+    #:
     UPC_EAN_EXTENSION = 17
 
 
 def read_codes(image, barcode_type=BarcodeType.NONE, try_harder=False, hybrid=False):
+    """
+    Reads codes from a PIL Image.
+
+    Args:
+        image (PIL.Image.Image): Image to read barcodes from.
+        barcode_type (zxinglight.BarcodeType): Barcode type to look for.
+        try_harder (bool): Spend more time trying to find a barcode.
+        hybrid (bool): Use Hybrid Binarizer instead of Global Binarizer. For more information,
+            see `ZXing's documentation`_.
+
+    Returns:
+        A list of barcode values.
+
+    .. _ZXing's documentation:
+        https://zxing.github.io/zxing/apidocs/com/google/zxing/Binarizer.html
+    """
+
     if not Image.isImageType(image):
         raise ValueError('Provided image is not a PIL image')