Datamatrix (#8853)

* Implement datamatrix barcode generation

* Update documentation

* Update package requirements

* Add unit test

* Raise error on empty barcode data

* Update docs/hooks.py

docs/docs/hooks.py

@@ -152,12 +152,13 @@ def on_config(config, *args, **kwargs):
     """
     rtd = os.environ.get('READTHEDOCS', False)
 
+    # Note: version selection is handled by RTD internally
     # Check for 'versions.json' file
     # If it does not exist, we need to fetch it from the RTD API
-    if os.path.exists(os.path.join(os.path.dirname(__file__), 'versions.json')):
-        print("Found 'versions.json' file")
-    else:
-        fetch_rtd_versions()
+    # if os.path.exists(os.path.join(os.path.dirname(__file__), 'versions.json')):
+    #    print("Found 'versions.json' file")
+    # else:
+    #    fetch_rtd_versions()
 
     if rtd:
         rtd_version = os.environ['READTHEDOCS_VERSION']

docs/docs/report/barcodes.md

@@ -6,10 +6,9 @@ title: Barcode Generation
 
 Both [report](./report.md) and [label](./labels.md) templates can render custom barcode data to in-line images.
 
-!!! info "img"
-    Barcode data must be rendered inside an `<img>` tag.
+### Barcode Template Tags
 
-Inside the template file (whether it be for printing a label or generating a custom report), the following code will need to be included at the top of the template file:
+To use the barcode tags inside a label or report template, you must load the `barcode` template tags at the top of the template file:
 
 ```html
 {% raw %}
@@ -18,12 +17,30 @@ Inside the template file (whether it be for printing a label or generating a cus
 {% endraw %}
 ```
 
-### 1D Barcode
+### Barcode Image Data
+
+The barcode template tags will generate an image tag with the barcode data encoded as a base64 image. The image data is intended to be rendered as an `img` tag:
+
+```html
+{% raw %}
+{% load barcode %}
+<img class='custom_class' src='{% barcode "12345678" %}'>
+{% endraw %}
+```
+
+## 1D Barcode
 
 !!! info "python-barcode"
     One dimensional barcodes (e.g. Code128) are generated using the [python-barcode](https://pypi.org/project/python-barcode/) library.
 
-To render a 1D barcode, use the `barcode` template tag, as shown in the example below:
+To render a 1D barcode, use the `barcode` template tag:
+
+::: report.templatetags.barcode.barcode
+    options:
+        show_docstring_description: False
+        show_source: False
+
+### Example
 
 ```html
 {% raw %}
@@ -36,6 +53,8 @@ To render a 1D barcode, use the `barcode` template tag, as shown in the example
 {% endraw %}
 ```
 
+### Additional Options
+
 The default barcode renderer will generate a barcode using [Code128](https://en.wikipedia.org/wiki/Code_128) rendering. However [other barcode formats](https://python-barcode.readthedocs.io/en/stable/supported-formats.html) are also supported:
 
 ```html
@@ -58,29 +77,102 @@ You can also pass further [python-barcode](https://python-barcode.readthedocs.io
 {% endraw %}
 ```
 
-### QR-Code
+## QR-Code
 
 !!! info "qrcode"
     Two dimensional QR codes are generated using the [qrcode](https://pypi.org/project/qrcode/) library.
 
 To render a QR code, use the `qrcode` template tag:
 
-```html
-{% raw %}
+::: report.templatetags.barcode.qrcode
+    options:
+        show_docstring_description: false
+        show_source: False
 
-{% load barcode %}
-
-<img class='custom_qr_class' src='{% qrcode "Hello world!" %}'>
-{% endraw %}
-```
-
-Additional parameters can be passed to the `qrcode` function for rendering:
+### Example
 
 ```html
 {% raw %}
-<img class='custom_qr_class' src='{% qrcode "Hello world!" fill_color="green" back_color="blue" %}'>
+{% extends "label/label_base.html" %}
+
+{% load l10n i18n barcode %}
+
+{% block style %}
+
+.qr {
+    position: absolute;
+    left: 0mm;
+    top: 0mm;
+    {% localize off %}
+    height: {{ height }}mm;
+    width: {{ height }}mm;
+    {% endlocalize %}
+}
+
+{% endblock style %}
+
+{% block content %}
+<img class='qr' src='{% qrcode "Hello world!" fill_color="white" back_color="blue" %}'>
+{% endblock content %}
 {% endraw %}
 ```
 
+which produces the following output:
+
+{% with id="qrcode", url="report/qrcode.png", description="QR Code" %}
+{% include 'img.html' %}
+{% endwith %}
+
+
 !!! tip "Documentation"
     Refer to the [qrcode library documentation](https://pypi.org/project/qrcode/) for more information
+
+
+## Data Matrix
+
+!!! info "ppf.datamatrix"
+    Data Matrix codes are generated using the [ppf.datamatrix](https://pypi.org/project/ppf-datamatrix/) library.
+
+[Data Matrix Codes](https://en.wikipedia.org/wiki/Data_Matrix) provide an alternative to QR codes for encoding data in a two-dimensional matrix. To render a Data Matrix code, use the `datamatrix` template tag:
+
+::: report.templatetags.barcode.datamatrix
+    options:
+        show_docstring_description: false
+        show_source: False
+
+### Example
+
+```html
+{% raw %}
+{% extends "label/label_base.html" %}
+
+{% load l10n i18n barcode %}
+
+{% block style %}
+
+.qr {
+    position: absolute;
+    left: 0mm;
+    top: 0mm;
+    {% localize off %}
+    height: {{ height }}mm;
+    width: {{ height }}mm;
+    {% endlocalize %}
+}
+
+{% endblock style %}
+
+{% block content %}
+
+
+<img class='qr' src='{% datamatrix "Foo Bar" back_color="yellow" %}'>
+
+{% endblock content %}
+{% endraw %}
+```
+
+which produces the following output:
+
+{% with id="datamatrix", url="report/datamatrix.png", description="Datamatrix barcode" %}
+{% include 'img.html' %}
+{% endwith %}