DOC transfered wiki to sphinx-doc

* changed structure of index-file
* copied the WIKI at commit 67601b2d33f5a3cf8e9633e6ad92cca286840680
* adapted the markdown to rst

doc/user/.directory

@@ -0,0 +1,5 @@
+[Dolphin]
+HeaderColumnWidths=270,74,108
+Timestamp=2015,12,27,17,3,8
+Version=3
+ViewMode=1

doc/user/dependencies.rst

@@ -0,0 +1,57 @@
+************
+Dependencies
+************
+
+Fedora
+------
+
+Fortunately everything is on Fedora repositories.
+
+::
+
+    # yum install python-imaging pyserial pyusb python-qrcode
+
+Ubuntu
+------
+
+Ultimately, this instructions also apply to Raspbian, in case you are
+interested to install python-escpos on your Raspberry with Raspbian.
+
+Install the packages available on distro repositories.
+
+::
+
+    # apt-get install python-imaging pyserial
+
+The packages which are not available at Ubuntu repositories need to be
+installed manually.
+
+pyusb
+^^^^^
+This is the python binding to libusb-1.0 
+
+* Get the latest tarball from `sourceforge <http://sourceforge.net/projects/pyusb/files/PyUSB%201.0/>`__
+* Build and install it
+
+::
+
+    # tar zxvf pyusb-1.*.tar.gz
+    # cd pyusb-1.*
+    # python setup.py build
+    # sudo python setup.py install
+
+python-qrcode
+^^^^^^^^^^^^^
+
+This is the python module to generate QR Codes
+
+* Checkout the latest code from `github <https://github.com/lincolnloop/python-qrcode>`__
+* Build and install it
+
+::
+
+    # git clone https://github.com/lincolnloop/python-qrcode
+    # cd python-qrcode
+    # python setup.py build
+    # sudo python setup.py install
+

doc/user/installation.rst

@@ -0,0 +1,40 @@
+************
+Installation
+************
+
+System preparation
+------------------
+
+1. Install the required
+   `dependencies <https://github.com/manpaz/python-escpos/wiki/Dependencies>`__
+
+2. Get the *Product ID* and *Vendor ID* from the lsusb command
+   ``# lsusb  Bus 002 Device 001: ID 1a2b:1a2b Device name``
+
+3. Create a udev rule to let users belonging to *dialout* group use the
+   printer. You can create the file
+   ``/etc/udev/rules.d/99-escpos.rules`` and add the following:
+   ``SUBSYSTEM=="usb", ATTRS{idVendor}=="1a2b", ATTRS{idProduct}=="1a2b", MODE="0664", GROUP="dialout"``
+   Replace *idVendor* and *idProduct* hex numbers with the ones that you
+   got from the previous step. Note that you can either, add yourself to
+   "dialout" group, or use another group you already belongs instead
+   "dialout" and set it in the ``GROUP`` parameter in the above rule.
+
+4. Restart udev ``# sudo service udev restart`` In some new systems it
+   is done with ``# sudo udevadm control --reload``
+
+Install
+-------
+
+* Clone python-escpos from github
+* Change directory to python-escpos and install the package
+
+   ::
+
+       # cd python-escpos
+       # python setup.py build
+       # sudo python setup.py install
+
+* Enjoy !!!
+
+

doc/user/methods.rst

@@ -0,0 +1,118 @@
+*******
+Methods
+*******
+
+.. note:: **TODO** Merge this page into the API-description.
+
+Escpos class
+------------
+
+Escpos inherits its methods to the printers. the following methods are
+defined:
+
+image("image\_name.ext")
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prints an image. Its adjust the size in order to print it.
+
+* ``image_name.ext`` is the complete file name and location of any image type (jpg, gif, png, bmp)
+
+Raises ``ImageSizeError`` exception.
+
+qr("text")
+^^^^^^^^^^
+
+Prints a QR code. The size has been adjusted to Version 4, so it can be
+enough small to be printed but also enough big to be read by a smart
+phone.
+
+* ``text`` Any text that needs to be QR encoded. It could be a slogan,
+  salutation, url, etc.
+
+barcode("code", "barcode\_type", width, height, "position", "font")
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prints a barcode.
+
+* ``code`` is an alphanumeric code to be printed as bar code
+* ``barcode_type`` must be one of the following type of codes:
+   
+  * UPC-A
+  * UPC-E
+  * EAN13
+  * EAN8
+  * CODE39
+  * ITF
+  * NW7
+   
+* ``width`` is a numeric value in the range between (1,255) *Default:* 64
+* ``height`` is a numeric value in the range between (2,6) *Default:* 3
+* ``position`` is where to place the code around the bars, could be one of the following values:
+  
+  * ABOVE
+  * BELOW
+  * BOTH
+  * OFF > *Default:* BELOW
+   
+* ``font`` is one of the 2 type of fonts, values could be:
+  
+  * A
+  * B > *Default:* A Raises ``BarcodeTypeError``, ``BarcodeSizeError``, ``BarcodeCodeError`` exceptions.
+    
+text("text")
+^^^^^^^^^^^^
+
+Prints raw text. Raises ``TextError`` exception.
+
+set("align", "font", "type", width, height)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set text properties.
+* ``align`` set horizontal position for text, the possible values are:
+   
+  * CENTER
+  * LEFT
+  * RIGHT > > *Default:* left
+   
+* ``font`` type could be ``A`` or ``B``. *Default:* A
+* ``type`` type could be ``B`` (Bold), ``U`` (Underline) or ``normal``. *Default:* normal
+* ``width`` is a numeric value, 1 is for regular size, and 2 is twice the standard size. *Default*: 1
+* ``height`` is a numeric value, 1 is for regular size and 2 is twice the standard size. *Default*: 1
+
+cut("mode")
+^^^^^^^^^^^
+
+Cut paper.
+* ``mode`` set a full or partial cut. *Default:* full
+
+**Partial cut is not implemented in all printers.**
+
+cashdraw(pin)
+^^^^^^^^^^^^^
+
+Sends a pulse to the cash drawer in the specified pin.
+
+* ``pin`` is a numeric value which defines the pin to be used to send the pulse, it could be 2 or 5. Raises ``CashDrawerError()``
+
+hw("operation")
+^^^^^^^^^^^^^^^
+
+Hardware operations.
+
+* ``operation`` is any of the following options:
+    
+  * INIT
+  * SELECT
+  * RESET
+
+control("align")
+^^^^^^^^^^^^^^^^
+
+Carrier feed and tabs.
+* ``align`` is a string which takes any of the following values:
+  
+  * LF *for Line Feed*
+  * FF *for Form Feed*
+  * CR *for Carriage Return*
+  * HT *for Horizontal Tab*
+  * VT *for Vertical Tab*

doc/user/printers.rst

@@ -0,0 +1,42 @@
+********
+Printers
+********
+
+.. note:: **TODO** Merge this page into the API-description.
+
+There 3 different type of printers:
+
+USB(idVendor, idProduct, interface, in\_ep, out\_ep)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Based on pyusb and libusb-1.0
+
+* ``idVendor`` is the Vendor ID
+* ``idProduct`` is the Product ID
+* ``interface`` is the USB device interface (default = 0)
+*  ``in_ep`` is the input end point (default = 0x82)
+* ``out_ep`` is the output end point (default = 0x01)
+
+Serial("devfile", baudrate, bytesize, timeout)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Based on pyserial, default values are based on the defaults set by
+DIP\_SWITCH\_1 on the documentation(hardware side).
+
+* ``devfile`` is an alphanumeric device file name under /dev filesystem (default = /ev/ttyS0)
+* ``baudrate`` is the Baud rate for serial transmission (default = 9600)
+* ``bytesize`` sets the serial buffer size (default = 8)
+* ``timeout`` defines Read/Write timeout (default = 1)
+
+Network("host", port)
+^^^^^^^^^^^^^^^^^^^^^
+
+Based on socket
+* ``host`` is an alphanumeric host name, could be either DNS host name or IP address.
+* ``port`` to write to (default = 9100)
+
+File("file\_name")
+^^^^^^^^^^^^^^^^^^
+
+Printcap printers
+* ``file_name`` is the full path to the device file name

doc/user/raspi.rst

@@ -0,0 +1,68 @@
+************
+Raspberry Pi
+************
+
+This instructions were tested on Raspbian.
+
+Unless you have done any distro with libusb-1.0 on the Raspberry Pi, the
+following instructions should works fine on your raspberry distro.
+
+Dependencies
+------------
+
+First, install the packages available on Raspbian.
+
+::
+
+    # apt-get install python-imaging python-serial python-setuptools
+
+PyUSB
+^^^^^
+
+PyUSB 1.0 is not available on Ubuntu, so you have to download and
+install it manually
+
+1. Download the latest tarball from
+   `Sourceforge <http://sourceforge.net/projects/pyusb/files/>`__
+2. Decompress the zip file
+3. Install the library
+
+   ::
+
+       # wget ...
+       # unzip pyusb*.zip
+       # cd pyusb*
+       # python setup.py build
+       # sudo python setup.py install
+
+python-qrcode
+^^^^^^^^^^^^^
+
+1. Checkout the code from github
+2. Install the library
+
+   ::
+
+       # git clone https://github.com/lincolnloop/python-qrcode
+       # cd python-qrcode
+       # python setup.py build
+       # sudo python setup.py install
+
+Installation
+------------
+
+If you have installed pyusb for libusb-1.0 then you need to:
+
+1. Download the latest file
+1. Decompress the file
+1. Install the library
+
+::
+
+    # git clone https://github.com/manpaz/python-escpos.git
+    # cd python-escpos
+    # python setup.py build
+    # sudo python setup.py install
+
+Now you can attach your printer and and test it with the example code in
+the project's `home <https://github.com/manpaz/python-escpos>`__

doc/user/todo.rst

@@ -0,0 +1,35 @@
+****
+TODO
+****
+
+Introduction
+------------
+
+python-escpos is the initial idea, from here we can start to build a
+robust library to get most of the ESC/POS printers working with this
+library.
+
+Eventually, this library must be able to cover almost all the defined
+models detailed in the ESC/POS Command Specification Manual.
+
+Details
+-------
+
+What things are planned to work on?
+
+Testing
+~~~~~~~
+
+* Test on many printers as possible (USB, Serial, Network)
+
+Design
+~~~~~~
+
+* Add all those sequences which are not common, but part of the ESC/POS
+  Command Specifications.
+
+  *  Port to Python 3
+  *  Windows compatibility (hidapi instead libusb?)
+  *  PDF417 support
+
+

doc/user/usage.rst

@@ -0,0 +1,138 @@
+*****
+Usage
+*****
+
+Define your printer
+-------------------
+
+USB printer
+^^^^^^^^^^^
+
+Before start creating your Python ESC/POS printer instance, you must see
+at your system for the printer parameters. This is done with the 'lsusb'
+command.
+
+First run the command to look for the "Vendor ID" and "Product ID", then
+write down the values, these values are displayed just before the name
+of the device with the following format:
+
+::
+
+    xxxx:xxxx
+
+Example:
+
+::
+
+    # lsusb
+    Bus 002 Device 001: ID 04b8:0202 Epson ...
+
+Write down the the values in question, then issue the following command
+so you can get the "Interface" number and "End Point"
+
+::
+
+    # lsusb -vvv -d xxxx:xxxx | grep iInterface
+        iInterface              0
+    # lsusb -vvv -d xxxx:xxxx | grep bEndpointAddress | grep OUT
+          bEndpointAddress     0x01  EP 1 OUT
+
+The first command will yields the "Interface" number that must be handy
+to have and the second yields the "Output Endpoint" address.
+
+**USB Printer initialization**
+
+::
+
+    Epson = printer.Usb(0x04b8,0x0202)
+
+By default the "Interface" number is "0" and the "Output Endpoint"
+address is "0x01", if you have other values then you can define with
+your instance. So, assuming that we have another printer where in\_ep is
+on 0x81 and out\_ep=0x02, then the printer definition should looks like:
+
+**Generic USB Printer initialization**
+
+::
+
+    Generic = printer.Usb(0x1a2b,0x1a2b,0,0x81,0x02)
+
+Network printer
+^^^^^^^^^^^^^^^
+
+You only need the IP of your printer, either because it is getting its
+IP by DHCP or you set it manually.
+
+**Network Printer initialization**
+
+::
+
+    Epson = printer.Network("192.168.1.99")
+
+Serial printer
+^^^^^^^^^^^^^^
+
+Must of the default values set by the DIP switches for the serial
+printers, have been set as default on the serial printer class, so the
+only thing you need to know is which serial port the printer is hooked
+up.
+
+**Serial printer initialization**
+
+::
+
+    Epson = printer.Serial("/dev/tty0")
+
+Other printers
+^^^^^^^^^^^^^^
+
+Some printers under /dev can't be used or initialized with any of the
+methods described above. Usually, those are printers used by printcap,
+however, if you know the device name, you could try the initialize
+passing the device node name.
+
+::
+
+    Epson = printer.File("/dev/usb/lp1")
+
+The default is "/dev/usb/lp0", so if the printer is located on that
+node, then you don't necessary need to pass the node name.
+
+Define your instance
+--------------------
+
+The following example demonstrate how to initialize the Epson TM-TI88IV
+on USB interface
+
+::
+
+    from escpos import *
+    """ Seiko Epson Corp. Receipt Printer M129 Definitions (EPSON TM-T88IV) """
+    Epson = printer.Usb(0x04b8,0x0202)
+    # Print text
+    Epson.text("Hello World\n")
+    # Print image
+    Epson.image("logo.gif")
+    # Print QR Code
+    Epson.qr("You can readme from your smartphone")
+    # Print barcode
+    Epson.barcode('1324354657687','EAN13',64,2,'','')
+    # Cut paper
+    Epson.cut()
+
+How to update your code for USB printers
+----------------------------------------
+
+Old code
+
+::
+
+    Epson = escpos.Escpos(0x04b8,0x0202,0)
+
+New code
+
+::
+
+    Epson = printer.Usb(0x04b8,0x0202)
+
+Nothe that "0" which is the interface number is no longer needed.