.. Flask-QRcode documentation master file, created by
   sphinx-quickstart on Wed Feb 28 11:03:06 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Flask-QRcode
=======================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Flask-QRcode is a concise Flask extension to easily render QR codes on Jinja2
templates using python-qrcode.

User's guide
============

It is very straightforward to use Flask-QRcode on your Flask projects, and you
can find a sample application with running examples on `the repository on
GitHub 
<https://github.com/marcoagner/Flask-QRcode/tree/master/sample_application>`_.

Installation
------------

You can install it from PyPi:
::

        $ pip install flask-qrcode

Or download the latest release from the `GitHub repository
<https://github.com/marcoagner/Flask-QRcode/releases>`_.

Note tha all the latest releases should be signed with the PGP key
`0x0dc77fc61ed3ecc4 <https://www.marcoagner.org/agner.asc>`_ (also found on
`keybase <https://keybase.io/marcoagner>`_).

Basic usage
-----------

**Extend the app:**
::

        from flask_qrcode import QRcode
        # [...]
        QRcode(app)
        # [...]

**Then use it within your templates:**
::

        {# Basic usage: #}
        <img src="{{ qrcode(STRING_TO_ENCODE) }}">

More examples
-------------

**Simple example:**
::

        <img src="{{ qrcode("Do you speak QR?")  }}">

.. image:: /_static/examples/simple-example.png

**Changing box size:**
::

        <img src="{{ qrcode("I'm bigger than you!", box_size=20)  }}">

.. image:: /_static/examples/shape-example-1.png

**Changing border size:**
::

        <img src="{{ qrcode("Whatever... can't touch me", border=10)  }}">

.. image:: /_static/examples/shape-example-2.png

**Changing QRcode error correction according to python-qrcode documentations:**
::

        <img src="{{ qrcode("You can read me even if I'm 30% hurt.", error_correction='H')  }}">

.. image:: /_static/examples/qrcode-example-1.png

**A "combo" example changing more than one parameter:**
::

        <img src="{{ qrcode("FATALITY", box_size=12, border=5)  }}">

.. image:: /_static/examples/combo-example-1.png

**Changing the color of the QR code:**
::

        <img src="{{ qrcode("You can see green front color and #CCC back color.", error_correction='H', back_color='ccc', fill_color='green')  }}">

.. image:: /_static/examples/color-example-1.png

**Rendering an icon inside the QR code (external link):**
::

        <img src="{{ qrcode("You can see a icon in QR code.", error_correction='H', icon_img='https://www.agner.io/icon.jpg')  }}">

.. image:: /_static/examples/icon-example-1.png

**Rendering an icon inside the QR code (local file):**
::

        <img src="{{ qrcode("Load icon image from static folder.", error_correction='H', icon_img='icon.jpg')  }}">

.. image:: /_static/examples/icon-example-2.png


Contributing
============

Thank you for considering contributing to this package.

As this is a simple package, the process is pretty straightforward...

1. Fork `this repository <https://github.com/marcoagner/flask-qrcode>`_
2. Checkout from master with to a feature branch with a name related to what is
   being contributed (e.g. "colored-qrcodes")

\*It's highly recommended that your contribution either creates a new feature,
fixes something OR refactors the code and does not mix these (e.g. one PR
fixing some existent feature and refactoring non-related code).

3. Install dependencies and flask_qrcode on editable mode
::

        $ pip install -e . # for installing flask_qrcode on editable mode

4. Do your magic
5. Provide new tests for your work and check that both this and the old ones
   are passing.
6. Pull Request!

Testing
=======

1. Install dependencies and flask_qrcode on editable mode
::

        $ pip install -e . # for installing flask_qrcode on editable mode

2. Run pytest
::

        $ python setup.py test # in package's root dir

Source code documentation
=========================

// Automatically generated by Sphinx's autodocs based on the source
code's docstrings.

* :ref:`genindex`
* :ref:`modindex`