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

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 %}

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 %}

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"

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

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

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

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 <https://github.com/receipt-print-hq/escpos-printer-db>`_.
+
+.. datatemplate:json:: ../../capabilities-data/dist/capabilities.json
+   :template: capabilities-template.jinja

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`.
+

doc/requirements.txt

@@ -10,3 +10,4 @@ sphinxcontrib-spelling>=7.2.0
 python-barcode>=0.11.0,<1
 importlib-metadata
 importlib_resources
+sphinxcontrib.datatemplates

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 </download/barcode.bin>` by `@mike42 <https://github.com/mike42>`_
 
+.. _advanced-usage-change-capabilities-profile:
+
 Advanced Usage: change capabilities-profile
 -------------------------------------------
 

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