Add printer profile list to documentation (#536)
* add first draft of printer profile listing * add todos * Update doc/capability_templates/capabilities-template.jinja * Update doc/capability_templates/capabilities-template.jinja * restructure documentation * add encoding list * add color and encoding table * add notes on usage * add feature table
This commit is contained in:
Patrick Kanzler
GitHub
parent
09a598883c
commit
60c4f481ae
|
|
@ -0,0 +1,28 @@
|
|||
{% for item in data.encodings %}
|
||||
{% set encoding = data.encodings[item] %}
|
||||
{% macro draw_with_underline(text, symbol='-') -%}
|
||||
{{ escape_rst(text) }}
|
||||
{{ escape_rst(text) | length * symbol }}
|
||||
{%- endmacro %}
|
||||
|
||||
{{ '.. _encoding-label-' + item + ':' }}
|
||||
|
||||
{{ draw_with_underline(encoding.name) }}
|
||||
|
||||
{{ escape_rst(encoding.notes) }}
|
||||
|
||||
Mapping Information
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
====================== ================================================================
|
||||
identifier {{ escape_rst(item) }}
|
||||
Name {{ escape_rst(encoding.name|default('Unknown')) }}
|
||||
Iconv Name {{ escape_rst(encoding.iconv|default('Unknown')) }}
|
||||
``python_encode`` Name {{ escape_rst(encoding.python_encode|default('Unknown')) }}
|
||||
====================== ================================================================
|
||||
|
||||
{% if encoding.data is defined %}
|
||||
{{ draw_with_underline('Code page data', symbol='^') }}
|
||||
{{ encoding.data }}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
{% for item in data.profiles %}
|
||||
{% set printer = data.profiles[item] %}
|
||||
{% macro draw_with_underline(text, symbol='-') -%}
|
||||
{{ escape_rst(text) }}
|
||||
{{ escape_rst(text) | length * symbol }}
|
||||
{%- endmacro %}
|
||||
{% macro abort(error) %}
|
||||
{{ None['[ERROR] ' ~ error][0] }}
|
||||
{% endmacro %}
|
||||
{% macro fill_line(text, total, symbol=' ') -%}
|
||||
{%- if total < text|length -%}
|
||||
{{- abort("Line cannot be filled: must be longer") -}}
|
||||
{%- endif -%}
|
||||
{{- text + ((total - text|length ) * symbol ) -}}
|
||||
{%- endmacro %}
|
||||
|
||||
{{ '.. _printer-label-' + item + ':' }}
|
||||
|
||||
{{ draw_with_underline(printer.name) }}
|
||||
{{ escape_rst(printer.notes) }}
|
||||
|
||||
You can select this profile in python-escpos with this identifier: ``{{ item }}``.
|
||||
(Set parameter to `profile='{{ item }}'`.)
|
||||
|
||||
Basic information
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
====================== ================================================================
|
||||
Name {{ escape_rst(printer.name|default('Unknown')) }}
|
||||
Vendor {{ escape_rst(printer.vendor|default('Unknown')) }}
|
||||
Media width (mm) {{ escape_rst(printer.media.width.mm|default('Unknown')|string) }}
|
||||
Media width (pixels) {{ escape_rst(printer.media.width.pixels|default('Unknown')|string) }}
|
||||
DPI {{ escape_rst(printer.media.dpi|default('Unknown')|string) }}
|
||||
====================== ================================================================
|
||||
|
||||
Fonts
|
||||
^^^^^
|
||||
|
||||
+------------------+------------------------------+-----------------------+
|
||||
| ID | Name | Columns |
|
||||
+==================+==============================+=======================+
|
||||
{% for id in printer.fonts -%}
|
||||
| {{ fill_line(escape_rst(id), 16) }} | {{ fill_line(escape_rst(printer.fonts[id].name), 28) }} | {{ fill_line(printer.fonts[id].columns|string, 21) }} |
|
||||
+------------------+------------------------------+-----------------------+
|
||||
{% endfor %}
|
||||
|
||||
|
||||
Colors
|
||||
^^^^^^
|
||||
|
||||
+------------------+----------------------------------------------------------------+
|
||||
| ID | Color |
|
||||
+==================+================================================================+
|
||||
{% for id in printer.colors -%}
|
||||
| {{ fill_line(escape_rst(id), 16) }} | {{ fill_line(escape_rst(printer.colors[id]), 62) }} |
|
||||
+------------------+----------------------------------------------------------------+
|
||||
{% endfor %}
|
||||
|
||||
|
||||
Feature support
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
+-----------------------------------+----------------------------+
|
||||
| Feature | Supported |
|
||||
+===================================+============================+
|
||||
{% for feature in printer.features -%}
|
||||
| {{ fill_line(escape_rst(feature), 33) }} | {{ fill_line(escape_rst(printer.features[feature]|string), 26) }} |
|
||||
+-----------------------------------+----------------------------+
|
||||
{% endfor %}
|
||||
|
||||
|
||||
Text code pages
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
+------------------+----------------------------------------------------------------+
|
||||
| ID | Encoding |
|
||||
+==================+================================================================+
|
||||
{% for id in printer.codePages -%}
|
||||
| {{ fill_line(escape_rst(id), 16) }} | {{ fill_line(':ref:`encoding-label-'+printer.codePages[id]+'`', 62) }} |
|
||||
+------------------+----------------------------------------------------------------+
|
||||
{% endfor %}
|
||||
|
||||
{% endfor %}
|
||||
|
|
@ -42,6 +42,7 @@ extensions = [
|
|||
"sphinx.ext.todo",
|
||||
"sphinx.ext.graphviz",
|
||||
"sphinx.ext.inheritance_diagram",
|
||||
"sphinxcontrib.datatemplates",
|
||||
"sphinxcontrib.spelling",
|
||||
]
|
||||
|
||||
|
|
@ -54,7 +55,7 @@ suppress_warnings = [
|
|||
todo_include_todos = True
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ["_templates"]
|
||||
templates_path = ["_templates", "capability_templates"]
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = ".rst"
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
***************
|
||||
Release process
|
||||
***************
|
||||
|
||||
* Update authors file
|
||||
* Update changelog
|
||||
* Set annotated tag for release and push to public github
|
||||
* Build wheel
|
||||
* Load wheel to PyPi
|
||||
|
|
@ -16,16 +16,25 @@ Content
|
|||
user/methods
|
||||
user/printers
|
||||
user/raspi
|
||||
user/todo
|
||||
user/usage
|
||||
user/barcode
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Printer profiles
|
||||
|
||||
printer_profiles/capabilities.rst
|
||||
printer_profiles/available-profiles.rst
|
||||
printer_profiles/available-encodings.rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Developer Documentation
|
||||
|
||||
dev/release-process
|
||||
dev/contributing
|
||||
dev/changelog
|
||||
dev/todo
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
|
|
|||
|
|
@ -0,0 +1,6 @@
|
|||
Available Encodings
|
||||
-------------------
|
||||
:Last Reviewed: 2023-07-29
|
||||
|
||||
.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
|
||||
:template: capabilities-template-encoding.jinja
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
.. _available-profiles:
|
||||
|
||||
Available Profiles
|
||||
------------------
|
||||
:Last Reviewed: 2023-07-29
|
||||
|
||||
The following list describes which printer profiles are
|
||||
available in this release.
|
||||
The existence of a profile is a hint, but no guarantee
|
||||
that this printer actually can be controlled by this library.
|
||||
|
||||
If you find any issues with the described capabilities,
|
||||
please open an issue in the
|
||||
`ESC/POS printer database <https://github.com/receipt-print-hq/escpos-printer-db>`_.
|
||||
|
||||
.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
|
||||
:template: capabilities-template.jinja
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
Capabilities
|
||||
------------
|
||||
:Last Reviewed: 2023-07-29
|
||||
|
||||
Since the used command set often differs between printers,
|
||||
a model for supporting different printers is implemented.
|
||||
This feature is called `capabilities`.
|
||||
|
||||
The `capabilities`-feature allows this library to know
|
||||
which features are supported.
|
||||
If no further information is specified, python-escpos will
|
||||
try to automatically use features based on the supplied information.
|
||||
|
||||
In order to use the `capabilities`-database, the printer instance
|
||||
simply has to be created with the parameter `profile` set to the
|
||||
relevant identifier.
|
||||
The identifier can be found in :ref:`available-profiles`.
|
||||
|
||||
This documentation describes the profiles in the database file that
|
||||
is bundled with this release.
|
||||
If another configuration is to be used, this chapter can be followed
|
||||
for information on how to sideload another `capabilities`-database:
|
||||
:ref:`advanced-usage-change-capabilities-profile`.
|
||||
|
||||
|
|
@ -10,3 +10,4 @@ sphinxcontrib-spelling>=7.2.0
|
|||
python-barcode>=0.11.0,<1
|
||||
importlib-metadata
|
||||
importlib_resources
|
||||
sphinxcontrib.datatemplates
|
||||
|
|
|
|||
|
|
@ -238,6 +238,8 @@ Here you can download an example, that will print a set of common barcodes:
|
|||
|
||||
* :download:`barcode.bin </download/barcode.bin>` by `@mike42 <https://github.com/mike42>`_
|
||||
|
||||
.. _advanced-usage-change-capabilities-profile:
|
||||
|
||||
Advanced Usage: change capabilities-profile
|
||||
-------------------------------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue