diff --git a/Makefile b/Makefile index 30cc6f6..93e92e0 100644 --- a/Makefile +++ b/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/ diff --git a/README.rst b/README.rst index 1061d91..29fea10 100644 --- a/README.rst +++ b/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 . + +.. _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/ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..7ba0ae7 --- /dev/null +++ b/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'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..fb50a0c --- /dev/null +++ b/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` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..50316de --- /dev/null +++ b/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 diff --git a/docs/reference.rst b/docs/reference.rst new file mode 100644 index 0000000..00c75db --- /dev/null +++ b/docs/reference.rst @@ -0,0 +1,5 @@ +Reference +========= + +.. automodule:: zxinglight + :members: BarcodeType, read_codes diff --git a/setup.py b/setup.py index 10bb6f3..f2f9622 100644 --- a/setup.py +++ b/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', diff --git a/zxinglight/__init__.py b/zxinglight/__init__.py index fce4862..41cd2d9 100644 --- a/zxinglight/__init__.py +++ b/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')