setop/python-escpos
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

further revise

Browse Source
This commit is contained in:
Patrick Kanzler 2023-08-10 01:32:23 +02:00
parent 58b50b1736
commit 9a7ac83f89
8 changed files with 76 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
CONTRIBUTING.rst
View File

@ -1,23 +1,32 @@
Contributing Contributing
============ ============
This project is open to any kind of contribution. You can help with improving the documentation, adding fixes to the :Last Reviewed: 2023-08-10
code, providing test cases in code or as a description or just spreading the word. Please feel free to create an
issue or pull request.
In order to reduce the amount of work for everyone please try to adhere to good practice.
The pull requests and issues will be prefilled with templates. Please fill in your information where applicable. This project is open to any kind of contribution.
You can help with improving the documentation, adding fixes to the
code, providing test cases in code or as a description or just
spreading the word.
Please feel free to create an issue or pull request.
In order to reduce the amount of work for everyone please try
to adhere to good practice.
This project uses `semantic versioning <https://semver.org/>`_ and tries to adhere to the proposed rules as The pull requests and issues will be prefilled with templates.
well as possible. Please fill in your information where applicable.
This project uses `semantic versioning <https://semver.org/>`_
and tries to adhere to the proposed rules as well as possible.
Author-list Author-list
----------- -----------
This project keeps a list of authors. This can be auto-generated by calling `./doc/generate-authors.sh`. This project keeps a list of authors.
When contributing the first time, please include a commit with the output of this script in place. This can be auto-generated by calling `./doc/generate-authors.sh`.
When contributing the first time, please include a commit with
the output of this script in place.
When you change your username or mail-address, please also update the `.mailmap` and the authors-list. When you change your username or mail-address, please also
update the `.mailmap` and the authors-list.
You can find a good documentation on the mapping-feature in the You can find a good documentation on the mapping-feature in the
`documentation of git-shortlog <https://git-scm.com/docs/git-shortlog#_mapping_authors>`_. `documentation of git-shortlog <https://git-scm.com/docs/git-shortlog#_mapping_authors>`_.
@ -33,31 +42,42 @@ Please format your contributions with black, otherwise they will be rejected.
GIT GIT
^^^ ^^^
The master-branch contains the main development of the project. A release to PyPi is marked with a tag The master-branch contains the main development of the project.
corresponding to the version. Issues are closed when they have been resolved by merging into the master-branch. A release to PyPi is marked with a tag corresponding to the version.
When you have a change to make, begin by creating a new branch from the HEAD of `python-escpos/master`. Issues are closed when they have been resolved by merging
into the master-branch.
When you have a change to make, begin by creating a new branch
from the HEAD of `python-escpos/master`.
Please try to group your commits into logical units. If you need to tidy up your branch, you can make use of a Please try to group your commits into logical units.
git feature called an 'interactive rebase' before making a pull request. A small, self-contained change-set is If you need to tidy up your branch, you can make use of a
easier to review, and improves the chance of your code being merged. git feature called an 'interactive rebase' before making a pull request.
Please also make sure that before creating your PR, your branch is rebased on a recent commit or you merged a recent A small, self-contained change-set is easier to review, and
commit into your branch. This way you can ensure that your PR is without merge conflicts. improves the chance of your code being merged.
Please also make sure that before creating your PR, your branch
is rebased on a recent commit or you merged a recent
commit into your branch.
This way you can ensure that your PR is without merge conflicts.
Docstrings Docstrings
^^^^^^^^^^ ^^^^^^^^^^
This project tries to have a good documentation. This project tries to have a good documentation.
Please add a docstring to every method and class. Have a look at existing methods and classes for the style. Please add a docstring to every method and class.
Have a look at existing methods and classes for the style.
We use basically standard rst-docstrings for Sphinx. We use basically standard rst-docstrings for Sphinx.
Test Test
^^^^ ^^^^
Try to write tests whenever possible. Our goal for the future is 100% coverage. Try to write tests whenever possible.
You can copy the structure from other testcases. Please remember to adapt the docstrings. Our goal for the future is 100% coverage.
You can copy the structure from other testcases.
Please remember to adapt the docstrings.
Further reading Further reading
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
For further best practices and hints on contributing please see the For further best practices and hints on contributing please see the
`contribution-guide <https://www.contribution-guide.org/>`_. Should there be any contradictions between this guide `contribution-guide <https://www.contribution-guide.org/>`_.
Should there be any contradictions between this guide
and the linked one, please stick to this text. and the linked one, please stick to this text.
Aside from that feel free to create an issue or write an email if anything is unclear. Aside from that feel free to create an issue or write an email if anything is unclear.

2
doc/dev/release-process.rst
View File

@ -1,6 +1,8 @@
Release process Release process
=============== ===============
:Last Reviewed: 2023-08-10
* Update authors file * Update authors file
* Update changelog * Update changelog
* Set annotated tag for release and push to public github * Set annotated tag for release and push to public github

2
doc/dev/todo.rst
View File

@ -1,6 +1,8 @@
TODO TODO
==== ====
:Last Reviewed: 2023-08-10
Open points and issues of the project are tracked in the GitHub issues. Open points and issues of the project are tracked in the GitHub issues.
Some annotations still remain in the code and should be moved over time Some annotations still remain in the code and should be moved over time
into the issue tracker. into the issue tracker.

7
doc/printer_profiles/available-encodings.rst
View File

@ -1,6 +1,11 @@
Available Encodings Available Encodings
------------------- -------------------
:Last Reviewed: 2023-07-29 :Last Reviewed: 2023-08-10
If you find any issues with the described encodings,
please open an issue in the
`ESC/POS printer database <https://github.com/receipt-print-hq/escpos-printer-db>`_.
The data shown here is directly taken from there.
.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json .. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
:template: capabilities-template-encoding.jinja :template: capabilities-template-encoding.jinja

3
doc/printer_profiles/available-profiles.rst
View File

@ -2,7 +2,7 @@
Available Profiles Available Profiles
------------------ ------------------
:Last Reviewed: 2023-07-29 :Last Reviewed: 2023-08-10
The following list describes which printer profiles are The following list describes which printer profiles are
available in this release. available in this release.
@ -12,6 +12,7 @@ that this printer actually can be controlled by this library.
If you find any issues with the described capabilities, If you find any issues with the described capabilities,
please open an issue in the please open an issue in the
`ESC/POS printer database <https://github.com/receipt-print-hq/escpos-printer-db>`_. `ESC/POS printer database <https://github.com/receipt-print-hq/escpos-printer-db>`_.
The data shown here is directly taken from there.
.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json .. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
:template: capabilities-template.jinja :template: capabilities-template.jinja

2
doc/printer_profiles/capabilities.rst
View File

@ -2,7 +2,7 @@
Capabilities Capabilities
------------ ------------
:Last Reviewed: 2023-07-29 :Last Reviewed: 2023-08-10
Since the used command set often differs between printers, Since the used command set often differs between printers,
a model for supporting different printers is implemented. a model for supporting different printers is implemented.

29
doc/user/barcode.rst
View File

@ -1,19 +1,29 @@
Printing Barcodes Printing Barcodes
----------------- -----------------
:Last Reviewed: 2023-05-16 :Last Reviewed: 2023-08-10
Many printers implement barcode printing natively. Many printers implement barcode printing natively.
This hardware renderered barcodes are fast but the supported formats are limited by the printer itself and different between models. This hardware renderered barcodes are fast but the supported
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. formats are limited by the printer itself and different between models.
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. However, almost all printers support printing images, so barcode
rendering can be performed externally by software and then sent
to the printer as an image.
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.
barcode-method barcode-method
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
Since version 3.0, the ``barcode`` method unifies the previous ``barcode`` (hardware) and ``soft_barcode`` (software) methods. Since version 3.0, the ``barcode`` method unifies the previous
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. ``barcode`` (hardware) and ``soft_barcode`` (software) methods.
To achieve this, it relies on the information contained in the escpos-printer-db profiles. It is able to choose automatically the best printer implementation
The chosen profile needs to match the capabilities of the printer as closely as possible. for barcode printing based on the capabilities of the printer
and the type of barcode desired.
To achieve this, it relies on the information contained in the
escpos-printer-db profiles.
The chosen profile needs to match the capabilities of the printer
as closely as possible.
.. py:currentmodule:: escpos.escpos .. py:currentmodule:: escpos.escpos
@ -33,4 +43,5 @@ For alphanumeric CODE128 you have to preface your payload with `{B`.
# print CODE128 012ABCDabcd # print CODE128 012ABCDabcd
p.barcode("{B012ABCDabcd", "CODE128", function_type="B") p.barcode("{B012ABCDabcd", "CODE128", function_type="B")
A very good description on CODE128 is also on `Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_. A very good description on CODE128 is also on
`Wikipedia <https://en.wikipedia.org/wiki/Code_128>`_.

2
doc/user/usage.rst
View File

@ -1,7 +1,7 @@
Usage Usage
===== =====
:Last Reviewed: 2017-06-10 :Last Reviewed: 2023-08-10
Define your printer Define your printer
------------------- -------------------