From 7925b3b432657e4bc776598917975b2a6cdfb29b 2022-01-13 15:44:24
From: Lance Edgar <lance@edbob.org>
Date: 2022-01-13 15:44:24
Subject: [PATCH] Add basic docs for existing label features

---

diff --git a/docs/api/index.rst b/docs/api/index.rst
index 977dd71547d9cc6ad17bd60bf85b567552297b91..bb768ab4e9ae32b8921917fdd2ffc49c7eded5e0 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -17,6 +17,7 @@ attributes and method signatures etc.
    rattail/batch/custorder
    rattail/batch/handheld
    rattail/batch/handlers
+   rattail/batch/labels
    rattail/batch/pricing
    rattail/batch/product
    rattail/batch/purchase
@@ -54,6 +55,7 @@ attributes and method signatures etc.
    rattail/importing/sqlalchemy
    rattail/reporting/index
    rattail/reporting/handlers
+   rattail/labels
    rattail/logging
    rattail/mail
    rattail/membership
diff --git a/docs/api/rattail/batch/labels.rst b/docs/api/rattail/batch/labels.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a18968c2aabe16ed2c608d41100e03025ad8cecd
--- /dev/null
+++ b/docs/api/rattail/batch/labels.rst
@@ -0,0 +1,6 @@
+
+``rattail.batch.labels``
+========================
+
+.. automodule:: rattail.batch.labels
+   :members:
diff --git a/docs/api/rattail/db/index.rst b/docs/api/rattail/db/index.rst
index f9929df60dabc312021b7e5b2be3bf98a0924620..f581a7b69ada81a17665a705d4701ec646738d3b 100644
--- a/docs/api/rattail/db/index.rst
+++ b/docs/api/rattail/db/index.rst
@@ -27,6 +27,7 @@
    model.batch.purchase
    model.batch.vendorcatalog
    model.datasync
+   model.labels
    model.people
    model.products
    model.purchase
diff --git a/docs/api/rattail/db/model.labels.rst b/docs/api/rattail/db/model.labels.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ce937d5cfc2ba45fae46d6d047410b20701c535b
--- /dev/null
+++ b/docs/api/rattail/db/model.labels.rst
@@ -0,0 +1,6 @@
+
+``rattail.db.model.labels``
+===========================
+
+.. automodule:: rattail.db.model.labels
+  :members:
diff --git a/docs/api/rattail/labels.rst b/docs/api/rattail/labels.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0c7fb3162710905c412b2c4f867289d105052580
--- /dev/null
+++ b/docs/api/rattail/labels.rst
@@ -0,0 +1,6 @@
+
+``rattail.labels``
+==================
+
+.. automodule:: rattail.labels
+   :members:
diff --git a/rattail/db/model/labels.py b/rattail/db/model/labels.py
index f218f091f479d100a21d7b02661f32b14528827c..9500ef06db8b4a572323b5bb5c576d5038831e2c 100644
--- a/rattail/db/model/labels.py
+++ b/rattail/db/model/labels.py
@@ -2,7 +2,7 @@
 ################################################################################
 #
 #  Rattail -- Retail Software Framework
-#  Copyright © 2010-2018 Lance Edgar
+#  Copyright © 2010-2022 Lance Edgar
 #
 #  This file is part of Rattail.
 #
@@ -43,18 +43,41 @@ class LabelProfile(Base):
     __versioned__ = {}
 
     uuid = uuid_column()
-    ordinal = sa.Column(sa.Integer())
+
+    ordinal = sa.Column(sa.Integer(), nullable=True, doc="""
+    Preference ordinal number for the profile.  Profiles are typically
+    sorted by this number, which means the lower the number the higher
+    the preference.
+    """)
 
     code = sa.Column(sa.String(length=30), nullable=True, doc="""
     Supposedly unique "code" for the label profile.  May be useful for
     identification of a common label type across nodes, for instance.
     """)
 
-    description = sa.Column(sa.String(length=50))
-    printer_spec = sa.Column(sa.String(length=255))
-    formatter_spec = sa.Column(sa.String(length=255))
-    format = sa.Column(sa.Text())
-    visible = sa.Column(sa.Boolean())
+    description = sa.Column(sa.String(length=50), nullable=True, doc="""
+    Description for the profile, to be displayed to the user.
+    """)
+
+    printer_spec = sa.Column(sa.String(length=255), nullable=True, doc="""
+    Factory spec for the label printer.  This normally references some
+    subclass of :class:`rattail.labels.LabelPrinter`.
+    """)
+
+    formatter_spec = sa.Column(sa.String(length=255), nullable=True, doc="""
+    Factory spec for the label formatter.  This normally references some
+    subclass of :class:`rattail.labels.LabelFormatter`.
+    """)
+
+    format = sa.Column(sa.Text(), nullable=True, doc="""
+    Format template used to generate label commands.  Syntax for this
+    may depend on the type of printer you have.
+    """)
+
+    # TODO: this should have default=True, or something?
+    visible = sa.Column(sa.Boolean(), nullable=True, doc="""
+    Visibility flag; set this to false to hide the profile from users.
+    """)
 
     sync_me = sa.Column(sa.Boolean(), nullable=True, doc="""
     Flag indicating whether this label profile should be synced across "all"