Rework docs and prepare for release at version 0.12.

Author: mmulqueen

README.md

@@ -1,14 +1,18 @@
+<img src="https://raw.githubusercontent.com/mmulqueen/pyStrich/main/docs/logo.png" alt="pyStrich" width="200">
+
 pyStrich
 ========
-pyStrich is a Python module to generate 1D and 2D barcodes. Currently it
-supports
+pyStrich is a Python module to generate 1D and 2D barcodes in PNG, SVG and other image formats. Currently it
+supports:
 
  * code39
  * code128
  * ean13
  * datamatrix
  * qrcode
 
+pyStrich only depends on Pillow and has no other dependencies.
+
 Available from PyPI: https://pypi.org/project/pyStrich/
 
 Documentation: https://www.method-b.uk/pyStrich/docs/

docs/changelog.rst

@@ -1,7 +1,7 @@
 Changelog
 =========
 
-0.12 — unreleased
+0.12 — 2026-05-09
 -----------------
 
 - New ``pystrich`` console script with a subcommand per format and PNG /
@@ -25,12 +25,13 @@ Changelog
   :class:`~pystrich.ean13.EAN13Encoder`.
 - The human-readable labels for 1D barcodes are rendered with bundled Courier Prime glyph outlines (SIL Open
   Font License).
-- DXF: :meth:`~pystrich.qrcode.QRCodeEncoder.get_dxf` and
-  :meth:`~pystrich.datamatrix.DataMatrixEncoder.get_dxf` now write the
-  correct ``$INSUNITS`` value for ``"in"``, ``"ft"``, ``"mi"``,
-  ``"cm"`` and ``"m"`` (previously any value other than ``"mm"`` was
-  silently treated as unspecified); you should now pass ``units=None``
-  if unspecified is desired.
+- DXF: ``get_dxf()`` on
+  :class:`~pystrich.qrcode.QRCodeEncoder` and
+  :class:`~pystrich.datamatrix.DataMatrixEncoder` now writes the correct
+  ``$INSUNITS`` value for ``"in"``, ``"ft"``, ``"mi"``, ``"cm"`` and
+  ``"m"`` (previously any value other than ``"mm"`` was silently treated
+  as unspecified); you should now pass ``units=None`` if unspecified is
+  desired.
 - All vector outputs accept a ``mark_shape`` keyword argument
   (:class:`~pystrich.marks.MarkShape`) selecting how matched cells are
   grouped and drawn: horizontal runs (the SVG / EPS default), one
@@ -50,13 +51,13 @@ Changelog
 
 .. note::
 
-   Erratum: the
-   :meth:`~pystrich.qrcode.QRCodeEncoder.get_dxf` and
-   :meth:`~pystrich.datamatrix.DataMatrixEncoder.get_dxf` docstrings
-   stated that ``inverse=True`` (the default) draws dark modules as
-   filled cells. In fact ``inverse=True`` draws the *light* modules;
-   ``inverse=False`` draws the dark ones. Behaviour is unchanged --
-   only the description was wrong. Corrected in 0.12.
+   Erratum: the ``get_dxf()`` docstrings on
+   :class:`~pystrich.qrcode.QRCodeEncoder` and
+   :class:`~pystrich.datamatrix.DataMatrixEncoder` stated that
+   ``inverse=True`` (the default) draws dark modules as filled cells.
+   In fact ``inverse=True`` draws the *light* modules; ``inverse=False``
+   draws the dark ones. Behaviour is unchanged -- only the description
+   was wrong. Corrected in 0.12.
 
 - Documentation: full Sphinx-built docs are now published at
   https://www.method-b.uk/pyStrich/docs/, covering each symbology, recipes

docs/code128.rst

@@ -17,38 +17,21 @@ Example
 
    from pystrich.code128 import Code128Encoder
 
-   encoder = Code128Encoder("PyStrich-2026")
-   encoder.save("code128-example.png")
+   encoder = Code128Encoder("WDBCA45D2HA327260")
+   encoder.save_svg("code128-example.svg")
 
-.. image:: examples/code128-example.png
-   :alt: Code 128 barcode encoding "PyStrich-2026".
+.. image:: examples/code128-example.svg
+   :alt: Code 128 barcode encoding "WDBCA45D2HA327260".
 
-Sizing
-------
+Sizing, label, font and layout
+------------------------------
 
 The ``bar_width`` argument to :meth:`~Code128Encoder.save` and
 :meth:`~Code128Encoder.get_imagedata` sets the pixel width of the narrowest
 bar (default ``3``).
 
-.. code-block:: python
-
-   encoder = Code128Encoder("PyStrich-2026")
-   encoder.save("code128-wide.png", bar_width=6)
-
-.. image:: examples/code128-wide.png
-   :alt: Code 128 barcode encoding "PyStrich-2026" rendered with bar_width=6.
-
-.. seealso::
-
-   :doc:`printing` for guidance on selecting ``bar_width`` for printed
-   output.
-
-Label, font and layout
-----------------------
-
 The ``options`` dict passed to :class:`Code128Encoder` controls the
-human-readable label and the surrounding layout (see also the identical
-options on :doc:`code39`). All keys are optional.
+human-readable label and the surrounding layout. All keys are optional.
 
 ``show_label``
    Whether to render the human-readable label underneath the bars. Defaults
@@ -66,6 +49,11 @@ options on :doc:`code39`). All keys are optional.
 ``bottom_border``
    Pixels of vertical space between the label and the bottom edge.
 
+.. seealso::
+
+   :doc:`printing` for guidance on selecting ``bar_width`` for printed
+   output.
+
 .. code-block:: python
 
    options = {
@@ -75,42 +63,55 @@ options on :doc:`code39`). All keys are optional.
        "ttf_fontsize": 24,
        # "ttf_font": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
    }
-   encoder = Code128Encoder("PyStrich-2026", options=options)
+   encoder = Code128Encoder("WDBCA45D2HA327260", options=options)
    encoder.save("code128-custom.png", bar_width=4)
 
 .. image:: examples/code128-custom.png
-   :alt: Code 128 barcode encoding "PyStrich-2026" with a taller image and larger label.
+   :alt: Code 128 barcode encoding "WDBCA45D2HA327260" with a taller image and larger label.
+
+Output formats
+--------------
 
 SVG output
-----------
+~~~~~~~~~~
 
 For embedding in web pages or any workflow that benefits from
 resolution-independent output, use :meth:`~Code128Encoder.save_svg` (or
 :meth:`~Code128Encoder.get_svg` to receive the SVG as a string).
 
 .. code-block:: python
 
-   Code128Encoder("PyStrich-2026").save_svg("code128.svg")
+   Code128Encoder("WDBCA45D2HA327260").save_svg("code128.svg")
 
 .. image:: examples/code128-example.svg
-   :alt: SVG Code 128 barcode encoding "PyStrich-2026".
+   :alt: SVG Code 128 barcode encoding "WDBCA45D2HA327260".
 
 The SVG's ``viewBox`` is in module units (one narrow bar = one unit), while
 ``width`` and ``height`` scale by ``bar_width``. The 10-module quiet zones
 mandated by the standard are applied automatically on each side.
 
 .. versionadded:: 0.12
 
+PNG output
+~~~~~~~~~~
+
+For raster output, use :meth:`~Code128Encoder.save` to write a PNG file or
+:meth:`~Code128Encoder.get_imagedata` to receive the raw PNG bytes.
+
+.. code-block:: python
+
+   Code128Encoder("WDBCA45D2HA327260").save("code128.png")
+
 EPS output
-----------
+~~~~~~~~~~
 
 For embedding in LaTeX (``\includegraphics``) or other vector print
 workflows, use :meth:`~Code128Encoder.save_eps` (or
 :meth:`~Code128Encoder.get_eps` to receive the EPS as a string).
 
 .. code-block:: python
 
-   Code128Encoder("PyStrich-2026").save_eps("code128.eps")
+   Code128Encoder("WDBCA45D2HA327260").save_eps("code128.eps")
 
 The ``bar_width`` argument is the width of the narrowest bar in PostScript
 points (1 point = 1/72 inch). The 10-module quiet zones are applied

docs/code39.rst

@@ -5,6 +5,10 @@ Code 39 is a 1D symbology widely used for industrial labelling. The default
 character set is uppercase letters, digits, space and ``-.$/+%``; pass
 ``full_ascii=True`` to encode any 7-bit character as a pair of symbols.
 
+.. code-block:: python
+
+   Code39Encoder("17 E North 32 St", full_ascii=True).save("code39-address.png")
+
 .. seealso::
 
    `Code 39 on Wikipedia <https://en.wikipedia.org/wiki/Code_39>`_ for
@@ -17,35 +21,19 @@ Example
 
    from pystrich.code39 import Code39Encoder
 
-   encoder = Code39Encoder("PART-1234")
-   encoder.save("code39-example.png")
+   encoder = Code39Encoder("64755")
+   encoder.save_svg("code39-example.svg")
 
-.. image:: examples/code39-example.png
-   :alt: Code 39 barcode encoding "PART-1234".
+.. image:: examples/code39-example.svg
+   :alt: Code 39 barcode encoding "64755".
 
-Sizing
-------
+Sizing, label, font and layout
+------------------------------
 
 The ``bar_width`` argument to :meth:`~Code39Encoder.save` and
 :meth:`~Code39Encoder.get_imagedata` sets the pixel width of the narrowest
 bar (default ``3``).
 
-.. code-block:: python
-
-   encoder = Code39Encoder("PART-1234")
-   encoder.save("code39-wide.png", bar_width=6)
-
-.. image:: examples/code39-wide.png
-   :alt: Code 39 barcode encoding "PART-1234" rendered with bar_width=6.
-
-.. seealso::
-
-   :doc:`printing` for guidance on selecting ``bar_width`` for printed
-   output.
-
-Label, font and layout
-----------------------
-
 The ``options`` dict passed to :class:`Code39Encoder` controls the
 human-readable label and the surrounding layout. All keys are optional.
 
@@ -64,6 +52,11 @@ human-readable label and the surrounding layout. All keys are optional.
 ``bottom_border``
    Pixels of vertical space between the label and the bottom edge.
 
+.. seealso::
+
+   :doc:`printing` for guidance on selecting ``bar_width`` for printed
+   output.
+
 .. code-block:: python
 
    options = {
@@ -73,42 +66,55 @@ human-readable label and the surrounding layout. All keys are optional.
        "ttf_fontsize": 24,
        # "ttf_font": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
    }
-   encoder = Code39Encoder("PART-1234", options=options)
+   encoder = Code39Encoder("64755", options=options)
    encoder.save("code39-custom.png", bar_width=4)
 
 .. image:: examples/code39-custom.png
-   :alt: Code 39 barcode encoding "PART-1234" with a taller image and larger label.
+   :alt: Code 39 barcode encoding "64755" with a taller image and larger label.
+
+Output formats
+--------------
 
 SVG output
-----------
+~~~~~~~~~~
 
 For embedding in web pages or any workflow that benefits from
 resolution-independent output, use :meth:`~Code39Encoder.save_svg` (or
 :meth:`~Code39Encoder.get_svg` to receive the SVG as a string).
 
 .. code-block:: python
 
-   Code39Encoder("PART-1234").save_svg("code39.svg")
+   Code39Encoder("64755").save_svg("code39.svg")
 
 .. image:: examples/code39-example.svg
-   :alt: SVG Code 39 barcode encoding "PART-1234".
+   :alt: SVG Code 39 barcode encoding "64755".
 
 The SVG's ``viewBox`` is in module units (one narrow bar = one unit), while
 ``width`` and ``height`` scale by ``bar_width``. The 10-module quiet zones
 mandated by the standard are applied automatically on each side.
 
 .. versionadded:: 0.12
 
+PNG output
+~~~~~~~~~~
+
+For raster output, use :meth:`~Code39Encoder.save` to write a PNG file or
+:meth:`~Code39Encoder.get_imagedata` to receive the raw PNG bytes.
+
+.. code-block:: python
+
+   Code39Encoder("64755").save("code39.png")
+
 EPS output
-----------
+~~~~~~~~~~
 
 For embedding in LaTeX (``\includegraphics``) or other vector print
 workflows, use :meth:`~Code39Encoder.save_eps` (or
 :meth:`~Code39Encoder.get_eps` to receive the EPS as a string).
 
 .. code-block:: python
 
-   Code39Encoder("PART-1234").save_eps("code39.eps")
+   Code39Encoder("64755").save_eps("code39.eps")
 
 The ``bar_width`` argument is the width of the narrowest bar in PostScript
 points (1 point = 1/72 inch). The 10-module quiet zones are applied