revise methods and installation

doc/user/installation.rst

@@ -1,24 +1,29 @@
 Installation
 ============
 
-:Last Reviewed: 2016-07-23
+:Last Reviewed: 2023-08-10
 
 Installation with PIP
 ---------------------
-Installation should be rather straight-forward. python-escpos is on PyPi, so you can simply enter:
+Installation should be rather straight-forward. python-escpos is on PyPi,
+so you can simply enter:
 
     ::
 
         pip install python-escpos
 
-This should install all necessary dependencies. Apart from that python-escpos should also be
+This should install all necessary dependencies. Apart from that
-available as a Debian package. If you want to always benefit from the newest stable releases you should probably
+python-escpos is for some versions also available as a Debian package.
-install from PyPi.
+If you want to always benefit from the newest stable releases you should
+always install from PyPi.
+If you use the ``--pre`` parameter for ``pip``, you will get the latest
+pre-release.
 
 Setup udev for USB-Printers
 ---------------------------
 1. Get the *Product ID* and *Vendor ID* from the lsusb command
-   ``# lsusb  Bus 002 Device 001: ID 1a2b:1a2b Device name``
+   ``# lsusb  Bus 002 Device 001: ID 1a2b:1a2b Device name``.
+   (Or whichever way your system supplies to get the PID and VID.)
 
 2. Create a udev rule to let users belonging to *dialout* group use the
    printer. You can create the file

doc/user/methods.rst

@@ -1,13 +1,13 @@
 Methods
 =======
 
-:Last Reviewed: 2017-01-25
+:Last Reviewed: 2023-08-10
 
 Escpos class
 ------------
 
-The core part of this libraries API is the Escpos class.
+The core part of the API of this library is the Escpos class.
-You use it by instantiating a  :doc:`printer <printers>` which is a child of Escpos.
+You use it by instantiating a :doc:`printer <printers>` which is a child of Escpos.
 The following methods are available:
 
 .. autoclass:: escpos.escpos.Escpos

src/escpos/constants.py

@@ -45,6 +45,8 @@ HW_RESET = ESC + b"\x3f\x0a\x00"  # Reset printer hardware
 _CASH_DRAWER = (
     lambda m, t1="", t2="": ESC + b"p" + m + six.int2byte(t1) + six.int2byte(t2)
 )
+
+#: decimal cash drawer kick sequence
 CD_KICK_DEC_SEQUENCE = (
     lambda esc, p, m, t1=50, t2=50: six.int2byte(esc)
     + six.int2byte(p)
@@ -52,8 +54,10 @@ CD_KICK_DEC_SEQUENCE = (
     + six.int2byte(t1)
     + six.int2byte(t2)
 )
-CD_KICK_2 = _CASH_DRAWER(b"\x00", 50, 50)  # Sends a pulse to pin 2 []
+#: Sends a pulse to pin 2 []
-CD_KICK_5 = _CASH_DRAWER(b"\x01", 50, 50)  # Sends a pulse to pin 5 []
+CD_KICK_2 = _CASH_DRAWER(b"\x00", 50, 50)
+#: Sends a pulse to pin 5 []
+CD_KICK_5 = _CASH_DRAWER(b"\x01", 50, 50)
 
 # Paper Cutter
 _CUT_PAPER = lambda m: GS + b"V" + m

src/escpos/escpos.py

@@ -1021,8 +1021,11 @@ class Escpos(object):
     def cashdraw(self, pin):
         """Send pulse to kick the cash drawer
 
-        Kick cash drawer on pin 2 or pin 5 according to default parameter.
+        Kick cash drawer on pin 2 (:py:const:`~escpos.constants.CD_KICK_2`)
-        For non default parameter send a decimal sequence i.e. [27,112,48] or [27,112,0,25,255]
+        or pin 5 (:py:const:`~escpos.constants.CD_KICK_5`)
+        according to the default parameters.
+        For non default parameters send a decimal sequence i.e.
+        [27,112,48] or [27,112,0,25,255].
 
         :param pin: pin number, 2 or 5 or list of decimals
         :raises: :py:exc:`~escpos.exceptions.CashDrawerError`
@@ -1094,7 +1097,7 @@ class Escpos(object):
     def print_and_feed(self, n=1):
         """Print data in print buffer and feed *n* lines
 
-        if n not in range (0, 255) then ValueError will be raised
+        If n not in range (0, 255) then a ValueError will be raised.
 
         :param n: number of n to feed. 0 <= n <= 255. default: 1
         :raises ValueError: if not 0 <= n <= 255
@@ -1144,17 +1147,24 @@ class Escpos(object):
     def panel_buttons(self, enable=True):
         """Controls the panel buttons on the printer (e.g. FEED)
 
-        When enable is set to False the panel buttons on the printer will be disabled. Calling the method with
+        When enable is set to False the panel buttons on the printer
-        enable=True or without argument will enable the panel buttons.
+        will be disabled.
+        Calling the method with `enable=True` or without argument
+        will enable the panel buttons.
 
-        If panel buttons are enabled, the function of the panel button, such as feeding, will be executed upon pressing
+        If panel buttons are enabled, the function of the panel button,
-        the button. If the panel buttons are disabled, pressing them will not have any effect.
+        such as feeding, will be executed upon pressing the button.
+        If the panel buttons are disabled, pressing them will not have
+        any effect.
 
-        This command is effective until the printer is initialized, reset or power-cycled. The default is enabled panel
+        This command is effective until the printer is initialized,
-        buttons.
+        resetted or power-cycled.
+        The default is enabled panel buttons.
 
-        Some panel buttons will always work, especially when printer is opened. See for more information the manual
+        Some panel buttons will always work, especially when the
-        of your printer and the escpos-command-reference.
+        printer is opened.
+        See for more information the manual of your printer and
+        the escpos-command-reference.
 
         :param enable: controls the panel buttons
         :rtype: None
@@ -1166,7 +1176,8 @@ class Escpos(object):
 
     def query_status(self, mode):
         """
-        Queries the printer for its status, and returns an array of integers containing it.
+        Queries the printer for its status, and returns an array
+        of integers containing it.
 
         :param mode: Integer that sets the status mode queried to the printer.
             - RT_STATUS_ONLINE: Printer status.