From 60c4f481ae9113c468054b7a235470dd7476dbcd Mon Sep 17 00:00:00 2001 From: Patrick Kanzler <4189642+patkan@users.noreply.github.com> Date: Sat, 29 Jul 2023 02:02:13 +0200 Subject: [PATCH] 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 --- .../capabilities-template-encoding.jinja | 28 +++++++ .../capabilities-template.jinja | 83 +++++++++++++++++++ doc/conf.py | 3 +- doc/dev/release-process.rst | 9 ++ doc/{user => dev}/todo.rst | 0 doc/index.rst | 11 ++- doc/printer_profiles/available-encodings.rst | 6 ++ doc/printer_profiles/available-profiles.rst | 17 ++++ doc/printer_profiles/capabilities.rst | 24 ++++++ doc/requirements.txt | 1 + doc/user/usage.rst | 2 + tox.ini | 1 + 12 files changed, 183 insertions(+), 2 deletions(-) create mode 100644 doc/capability_templates/capabilities-template-encoding.jinja create mode 100644 doc/capability_templates/capabilities-template.jinja create mode 100644 doc/dev/release-process.rst rename doc/{user => dev}/todo.rst (100%) create mode 100644 doc/printer_profiles/available-encodings.rst create mode 100644 doc/printer_profiles/available-profiles.rst create mode 100644 doc/printer_profiles/capabilities.rst diff --git a/doc/capability_templates/capabilities-template-encoding.jinja b/doc/capability_templates/capabilities-template-encoding.jinja new file mode 100644 index 0000000..1b204cc --- /dev/null +++ b/doc/capability_templates/capabilities-template-encoding.jinja @@ -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 %} \ No newline at end of file diff --git a/doc/capability_templates/capabilities-template.jinja b/doc/capability_templates/capabilities-template.jinja new file mode 100644 index 0000000..55455b6 --- /dev/null +++ b/doc/capability_templates/capabilities-template.jinja @@ -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 %} \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 9696642..50ad559 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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" diff --git a/doc/dev/release-process.rst b/doc/dev/release-process.rst new file mode 100644 index 0000000..740560a --- /dev/null +++ b/doc/dev/release-process.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 diff --git a/doc/user/todo.rst b/doc/dev/todo.rst similarity index 100% rename from doc/user/todo.rst rename to doc/dev/todo.rst diff --git a/doc/index.rst b/doc/index.rst index 4b5eea7..07ce151 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 diff --git a/doc/printer_profiles/available-encodings.rst b/doc/printer_profiles/available-encodings.rst new file mode 100644 index 0000000..2133d60 --- /dev/null +++ b/doc/printer_profiles/available-encodings.rst @@ -0,0 +1,6 @@ +Available Encodings +------------------- +:Last Reviewed: 2023-07-29 + +.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json + :template: capabilities-template-encoding.jinja \ No newline at end of file diff --git a/doc/printer_profiles/available-profiles.rst b/doc/printer_profiles/available-profiles.rst new file mode 100644 index 0000000..d179384 --- /dev/null +++ b/doc/printer_profiles/available-profiles.rst @@ -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 `_. + +.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json + :template: capabilities-template.jinja diff --git a/doc/printer_profiles/capabilities.rst b/doc/printer_profiles/capabilities.rst new file mode 100644 index 0000000..c2b333a --- /dev/null +++ b/doc/printer_profiles/capabilities.rst @@ -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`. + diff --git a/doc/requirements.txt b/doc/requirements.txt index d212805..823892f 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -10,3 +10,4 @@ sphinxcontrib-spelling>=7.2.0 python-barcode>=0.11.0,<1 importlib-metadata importlib_resources +sphinxcontrib.datatemplates diff --git a/doc/user/usage.rst b/doc/user/usage.rst index 8dec9ce..983dc7b 100644 --- a/doc/user/usage.rst +++ b/doc/user/usage.rst @@ -238,6 +238,8 @@ Here you can download an example, that will print a set of common barcodes: * :download:`barcode.bin ` by `@mike42 `_ +.. _advanced-usage-change-capabilities-profile: + Advanced Usage: change capabilities-profile ------------------------------------------- diff --git a/tox.ini b/tox.ini index dbc2a0e..1adcd45 100644 --- a/tox.ini +++ b/tox.ini @@ -32,6 +32,7 @@ deps = sphinx>=3.0.0 setuptools_scm python-barcode sphinxcontrib-spelling>=7.2.0 + sphinxcontrib.datatemplates sphinx_rtd_theme commands = sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html