Skip to content

Commit 2b62c8e

Browse files
patkanpatkan
authored
modernize and cleanup documentation (#542)
* disable system packages on rtd * install pycups on rtd * enable cups binding in documentation * document CupsPrinter * fix formatting * revise methods and installation * revise user/printers * revise raspi section * further revise
1 parent 4c2dcdf commit 2b62c8e

18 files changed

Lines changed: 174 additions & 103 deletions

‎.readthedocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,4 @@ python:
2525
- requirements: doc/requirements.txt
2626
- method: pip
2727
path: .
28-
system_packages: true
28+
system_packages: false

‎CONTRIBUTING.rst‎

Lines changed: 42 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,32 @@
11
Contributing
22
============
33

4-
This project is open to any kind of contribution. You can help with improving the documentation, adding fixes to the
5-
code, providing test cases in code or as a description or just spreading the word. Please feel free to create an
6-
issue or pull request.
7-
In order to reduce the amount of work for everyone please try to adhere to good practice.
4+
:Last Reviewed: 2023-08-10
85

9-
The pull requests and issues will be prefilled with templates. Please fill in your information where applicable.
6+
This project is open to any kind of contribution.
7+
You can help with improving the documentation, adding fixes to the
8+
code, providing test cases in code or as a description or just
9+
spreading the word.
10+
Please feel free to create an issue or pull request.
11+
In order to reduce the amount of work for everyone please try
12+
to adhere to good practice.
1013

11-
This project uses `semantic versioning <https://semver.org/>`_ and tries to adhere to the proposed rules as
12-
well as possible.
14+
The pull requests and issues will be prefilled with templates.
15+
Please fill in your information where applicable.
16+
17+
This project uses `semantic versioning <https://semver.org/>`_
18+
and tries to adhere to the proposed rules as well as possible.
1319

1420
Author-list
1521
-----------
1622

17-
This project keeps a list of authors. This can be auto-generated by calling `./doc/generate-authors.sh`.
18-
When contributing the first time, please include a commit with the output of this script in place.
23+
This project keeps a list of authors.
24+
This can be auto-generated by calling `./doc/generate-authors.sh`.
25+
When contributing the first time, please include a commit with
26+
the output of this script in place.
1927

20-
When you change your username or mail-address, please also update the `.mailmap` and the authors-list.
28+
When you change your username or mail-address, please also
29+
update the `.mailmap` and the authors-list.
2130
You can find a good documentation on the mapping-feature in the
2231
`documentation of git-shortlog <https://git-scm.com/docs/git-shortlog#_mapping_authors>`_.
2332

@@ -33,31 +42,42 @@ Please format your contributions with black, otherwise they will be rejected.
3342

3443
GIT
3544
^^^
36-
The master-branch contains the main development of the project. A release to PyPi is marked with a tag
37-
corresponding to the version. Issues are closed when they have been resolved by merging into the master-branch.
38-
When you have a change to make, begin by creating a new branch from the HEAD of `python-escpos/master`.
45+
The master-branch contains the main development of the project.
46+
A release to PyPi is marked with a tag corresponding to the version.
47+
Issues are closed when they have been resolved by merging
48+
into the master-branch.
49+
When you have a change to make, begin by creating a new branch
50+
from the HEAD of `python-escpos/master`.
3951

40-
Please try to group your commits into logical units. If you need to tidy up your branch, you can make use of a
41-
git feature called an 'interactive rebase' before making a pull request. A small, self-contained change-set is
42-
easier to review, and improves the chance of your code being merged.
43-
Please also make sure that before creating your PR, your branch is rebased on a recent commit or you merged a recent
44-
commit into your branch. This way you can ensure that your PR is without merge conflicts.
52+
Please try to group your commits into logical units.
53+
If you need to tidy up your branch, you can make use of a
54+
git feature called an 'interactive rebase' before making a pull request.
55+
A small, self-contained change-set is easier to review, and
56+
improves the chance of your code being merged.
57+
Please also make sure that before creating your PR, your branch
58+
is rebased on a recent commit or you merged a recent
59+
commit into your branch.
60+
This way you can ensure that your PR is without merge conflicts.
4561

4662
Docstrings
4763
^^^^^^^^^^
4864
This project tries to have a good documentation.
49-
Please add a docstring to every method and class. Have a look at existing methods and classes for the style.
65+
Please add a docstring to every method and class.
66+
Have a look at existing methods and classes for the style.
5067
We use basically standard rst-docstrings for Sphinx.
5168

5269
Test
5370
^^^^
54-
Try to write tests whenever possible. Our goal for the future is 100% coverage.
55-
You can copy the structure from other testcases. Please remember to adapt the docstrings.
71+
Try to write tests whenever possible.
72+
Our goal for the future is 100% coverage.
73+
You can copy the structure from other testcases.
74+
Please remember to adapt the docstrings.
5675

5776
Further reading
5877
^^^^^^^^^^^^^^^
5978
For further best practices and hints on contributing please see the
60-
`contribution-guide <https://www.contribution-guide.org/>`_. Should there be any contradictions between this guide
79+
`contribution-guide <https://www.contribution-guide.org/>`_.
80+
Should there be any contradictions between this guide
6181
and the linked one, please stick to this text.
6282
Aside from that feel free to create an issue or write an email if anything is unclear.
6383

‎doc/dev/release-process.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Release process
22
===============
33

4+
:Last Reviewed: 2023-08-10
5+
46
* Update authors file
57
* Update changelog
68
* Set annotated tag for release and push to public github

‎doc/dev/todo.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
TODO
22
====
33

4+
:Last Reviewed: 2023-08-10
5+
46
Open points and issues of the project are tracked in the GitHub issues.
57
Some annotations still remain in the code and should be moved over time
68
into the issue tracker.

‎doc/printer_profiles/available-encodings.rst‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
Available Encodings
22
-------------------
3-
:Last Reviewed: 2023-07-29
3+
:Last Reviewed: 2023-08-10
4+
5+
If you find any issues with the described encodings,
6+
please open an issue in the
7+
`ESC/POS printer database <https://github.com/receipt-print-hq/escpos-printer-db>`_.
8+
The data shown here is directly taken from there.
49

510
.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
611
:template: capabilities-template-encoding.jinja

‎doc/printer_profiles/available-profiles.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Available Profiles
44
------------------
5-
:Last Reviewed: 2023-07-29
5+
:Last Reviewed: 2023-08-10
66

77
The following list describes which printer profiles are
88
available in this release.
@@ -12,6 +12,7 @@ that this printer actually can be controlled by this library.
1212
If you find any issues with the described capabilities,
1313
please open an issue in the
1414
`ESC/POS printer database <https://github.com/receipt-print-hq/escpos-printer-db>`_.
15+
The data shown here is directly taken from there.
1516

1617
.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
1718
:template: capabilities-template.jinja

‎doc/printer_profiles/capabilities.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Capabilities
44
------------
5-
:Last Reviewed: 2023-07-29
5+
:Last Reviewed: 2023-08-10
66

77
Since the used command set often differs between printers,
88
a model for supporting different printers is implemented.

‎doc/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ python-barcode>=0.11.0,<1
1111
importlib-metadata
1212
importlib_resources
1313
sphinxcontrib.datatemplates
14+
pycups

‎doc/user/barcode.rst‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,29 @@
11
Printing Barcodes
22
-----------------
33

4-
:Last Reviewed: 2023-05-16
4+
:Last Reviewed: 2023-08-10
55

66
Many printers implement barcode printing natively.
7-
This hardware renderered barcodes are fast but the supported formats are limited by the printer itself and different between models.
8-
However, almost all printers support printing images, so barcode renderization can be performed externally by software and then sent to the printer as an image.
9-
As a drawback, this operation is much slower and the user needs to know and choose the image implementation method supported by the printer's commandset.
7+
This hardware renderered barcodes are fast but the supported
8+
formats are limited by the printer itself and different between models.
9+
However, almost all printers support printing images, so barcode
10+
rendering can be performed externally by software and then sent
11+
to the printer as an image.
12+
As a drawback, this operation is much slower and the user needs
13+
to know and choose the image implementation method supported by
14+
the printer's commandset.
1015

1116
barcode-method
1217
~~~~~~~~~~~~~~
13-
Since version 3.0, the ``barcode`` method unifies the previous ``barcode`` (hardware) and ``soft_barcode`` (software) methods.
14-
It is able to choose automatically the best printer implementation for barcode printing based on the capabilities of the printer and the type of barcode desired.
15-
To achieve this, it relies on the information contained in the escpos-printer-db profiles.
16-
The chosen profile needs to match the capabilities of the printer as closely as possible.
18+
Since version 3.0, the ``barcode`` method unifies the previous
19+
``barcode`` (hardware) and ``soft_barcode`` (software) methods.
20+
It is able to choose automatically the best printer implementation
21+
for barcode printing based on the capabilities of the printer
22+
and the type of barcode desired.
23+
To achieve this, it relies on the information contained in the
24+
escpos-printer-db profiles.
25+
The chosen profile needs to match the capabilities of the printer
26+
as closely as possible.
1727

1828
.. py:currentmodule:: escpos.escpos
1929
@@ -33,4 +43,5 @@ For alphanumeric CODE128 you have to preface your payload with `{B`.
3343
# print CODE128 012ABCDabcd
3444
p.barcode("{B012ABCDabcd", "CODE128", function_type="B")
3545
36-
A very good description on CODE128 is also on `Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_.
46+
A very good description on CODE128 is also on
47+
`Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_.

‎doc/user/installation.rst‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,31 @@
1+
.. _user_installation:
2+
13
Installation
24
============
35

4-
:Last Reviewed: 2016-07-23
6+
:Last Reviewed: 2023-08-10
57

68
Installation with PIP
79
---------------------
8-
Installation should be rather straight-forward. python-escpos is on PyPi, so you can simply enter:
10+
Installation should be rather straight-forward. python-escpos is on PyPi,
11+
so you can simply enter:
912

1013
::
1114

1215
pip install python-escpos
1316

14-
This should install all necessary dependencies. Apart from that python-escpos should also be
15-
available as a Debian package. If you want to always benefit from the newest stable releases you should probably
16-
install from PyPi.
17+
This should install all necessary dependencies. Apart from that
18+
python-escpos is for some versions also available as a Debian package.
19+
If you want to always benefit from the newest stable releases you should
20+
always install from PyPi.
21+
If you use the ``--pre`` parameter for ``pip``, you will get the latest
22+
pre-release.
1723

1824
Setup udev for USB-Printers
1925
---------------------------
2026
1. Get the *Product ID* and *Vendor ID* from the lsusb command
21-
``# lsusb Bus 002 Device 001: ID 1a2b:1a2b Device name``
27+
``# lsusb Bus 002 Device 001: ID 1a2b:1a2b Device name``.
28+
(Or whichever way your system supplies to get the PID and VID.)
2229

2330
2. Create a udev rule to let users belonging to *dialout* group use the
2431
printer. You can create the file

0 commit comments

Comments
 (0)