Docs: profile usage additions and clarifications (#677)

* Add link to github

* Add profile params to 'Documentation and Usage'

* More profile additions and clarifications

* Fix code style

* Fix Include link to github in documentation topbar

* Fix Black code style

* Fix GH link

* Fix GH link path

---------

Co-authored-by: Patrick Kanzler <4189642+patkan@users.noreply.github.com>

README.rst

@@ -59,7 +59,7 @@ Another example based on the Network printer class:
 
     from escpos.printer import Network
 
-    kitchen = Network("192.168.1.100") #Printer IP Address
+    kitchen = Network("192.168.1.100", profile="TM-T88III") #Printer IP Address
     kitchen.text("Hello World\n")
     kitchen.barcode('4006381333931', 'EAN13', 64, 2, '', '')
     kitchen.cut()
@@ -71,18 +71,22 @@ Another example based on the Serial printer class:
     from escpos.printer import Serial
 
     """ 9600 Baud, 8N1, Flow Control Enabled """
-    p = Serial(devfile='/dev/tty.usbserial',
+    p = Serial(
-               baudrate=9600,
+        devfile='/dev/tty.usbserial',
-               bytesize=8,
+        baudrate=9600,
-               parity='N',
+        bytesize=8,
-               stopbits=1,
+        parity='N',
-               timeout=1.00,
+        stopbits=1,
-               dsrdtr=True)
+        timeout=1.00,
+        dsrdtr=True,
+        profile="TM-T88III"
+    )
 
     p.text("Hello World\n")
     p.qr("You can readme from your smartphone")
     p.cut()
 
+.. note:: It is highly recommended to include a matching profile to inform python-escpos about the printer's capabilities.
 
 The full project-documentation is available on
 `Read the Docs <https://python-escpos.readthedocs.io>`_.

doc/conf.py

@@ -143,6 +143,14 @@ else:
 # documentation.
 # html_theme_options = {}
 
+# Show a 'Edit on GitHub' link instead of 'View page source'
+html_context = {
+    "display_github": True,
+    "github_user": "python-escpos",
+    "github_repo": "python-escpos",
+    "github_version": "master/doc/",
+}
+
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
 

doc/user/usage.rst

@@ -1,7 +1,7 @@
 Usage
 =====
 
-:Last Reviewed: 2023-08-10
+:Last Reviewed: 2025-02-16
 
 Define your printer
 -------------------
@@ -113,7 +113,7 @@ on a USB interface.
 
     from escpos import *
     """ Seiko Epson Corp. Receipt Printer M129 Definitions (EPSON TM-T88IV) """
-    p = printer.Usb(0x04b8,0x0202)
+    p = printer.Usb(0x04b8,0x0202, profile="TM-T88IV")
     # Print text
     p.text("Hello World\n")
     # Print image
@@ -180,6 +180,7 @@ An example file printer::
     printer:
             type: File
             devfile: /dev/someprinter
+            profile: TM-U220
 
 And for a network printer::
 
@@ -187,6 +188,7 @@ And for a network printer::
             type: Network
             host: 127.0.0.1
             port: 9000
+            profile: TM-U220
 
 An USB-printer could be defined by::
 
@@ -196,6 +198,7 @@ An USB-printer could be defined by::
             idProduct: 0x5678
             in_ep: 0x66
             out_ep: 0x01
+            profile: TM-U220
 
 Printing text right
 -------------------
@@ -250,8 +253,8 @@ Here you can download an example, that will print a set of common barcodes:
 
 .. _advanced-usage-change-capabilities-profile:
 
-Advanced Usage: change capabilities-profile
+Advanced Usage: change where is the capabilities-profile
--------------------------------------------
+--------------------------------------------------------
 
 Packaged together with the escpos-code is a capabilities-file. This file in
 JSON-format describes the capabilities of different printers. It is developed and hosted in