Merge pull request #259 from inventree/label-printing

Label printing

docs/app/stock.md

@@ -150,6 +150,18 @@ Select the *assign barcode* action to scan this third-party barcode and assign i
 
 This barcode can then be used to track the stock item.
 
+#### Print Label
+
+If the server supports [label printing plugins](../extend/plugins/label.md), then an option to print a label for the selected stock item:
+
+{% with id="label_print_1", url="app/stock_print_label_1.png", description="Print label via plugin" %}
+{% include 'app_img.html' %}
+{% endwith %}
+
+{% with id="label_print_2", url="app/stock_print_label_2", description="Print label via plugin" %}
+{% include 'app_img.html' %}
+{% endwith %}
+
 ### Edit Stock Item
 
 To edit the stock item details, select the *Edit* button in the top right corner of the screen:

docs/extend/plugins.md

@@ -7,15 +7,19 @@ title: Plugins
 The InvenTree server code supports an extensible plugin architecture, allowing custom plugins to be integrated directly into the database server. This allows development of complex behaviours which are decoupled from core InvenTree code.
 
 Plugins can be added from multiple sources:
-- InvenTree built-in plugins are located in the directory `./InvenTree/plugin/builtin`.  
-- Custom plugins should be placed  in the directory `./InvenTree/plugins`.
-- Plugins can be installed via PIP (python package manager)
 
-Plugins are discovered and loaded when the server is started.
+- Plugins can be installed via PIP (python package manager)
+- Custom plugins should be placed in the directory `./InvenTree/plugins`.
+- InvenTree built-in plugins are located in the directory `./InvenTree/plugin/builtin`.  
+
+Note: Plugins are discovered and loaded only when the server is started.
 
 !!! info "Enable Plugin Support"
     To enable custom plugins, plugin support must be activated in the [server configuration](../start/config.md).
 
+!!! question "Have you tried turning it off and on again?"
+    When new plugins are installed (and activated), both the web server and background worker must be restarted.
+
 ### Plugin Base Class
 
 Custom plugins must inherit from the [IntegrationPluginBase class](https://github.com/inventree/InvenTree/blob/master/InvenTree/plugin/integration.py). Any plugins installed via the methods outlined above will be "discovered" when the InvenTree server launches.
@@ -43,11 +47,11 @@ A *PluginConfig* database entry will be created for each plugin "discovered" whe
 The configuration entries must be enabled via the [InvenTree admin interface](../settings/admin.md).
 
 !!! warning "Disabled by Default"
-    Newly discovered plugins are disabled by default, and must be manually enabled by an admin user
+    Newly discovered plugins are disabled by default, and must be manually enabled (in the admin interface) by a user with staff privileges.
 
 ### Plugin Mixins
 
-Common use cases are covered by pre-supplied modules in the form of mixins (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
+Common use cases are covered by pre-supplied modules in the form of *mixins* (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
 
 Supported mixin classes are:
 
@@ -56,6 +60,7 @@ Supported mixin classes are:
 - [AppMixin](./plugins/app.md)
 - [BarcodeMixin](./plugins/barcode.md)
 - [EventMixin](./plugins/event.md)
+- [LabelPrintingMixin](./plugins/label.md)
 - [NavigationMixin](./plugins/navigation.md)
 - [ScheduleMixin](./plugins/schedule.md)
 - [SettingsMixin](./plugins/settings.md)
@@ -65,10 +70,20 @@ Supported mixin classes are:
 
 Plugins can either be loaded from paths in the InvenTree install directory or as a plugin installed via pip. We recommend installation via pip as this enables hassle-free upgrades.
 
-For development new plugins can be placed ina a subdirectory in `src/InvenTree/plugins`. Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`. These are not loaded in production mode.
+### Builtin Plugins
 
-### Plugin Installation File
+Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`. These are not loaded in production mode.
+
+### Local Directory
+
+Custom plugins can be placed in the `src/InvenTree/plugins/` directory, where they will be automatically discovered. This can be useful for developing and testing plugins, but can prove more difficult in production (e.g. when using Docker). 
+
+### Plugin Installation File (PIP)
 
 Plugins installation can be simplified by providing a list of plugins in a plugin configuration file. This file (by default, 'plugins.txt' in the same directory as the server configuration file) contains a list of required plugin packages.
 
-Plugins can be installed from this file by simply running the command `invoke plugins`.
+Plugins can be then installed from this file by simply running the command `invoke plugins`.
+
+!!! success "Auto Update"
+    When the server installation is updated via the `invoke update` command, the plugins (as specified in *plugins.txt*) will also be updated automatically.
+

docs/extend/plugins/label.md

@@ -0,0 +1,52 @@
+---
+title: Label Mixin
+---
+
+## LabelPrintingMixin
+
+The `LabelPrintingMixin` class enables plugins to print labels directly to a connected printer. Custom plugins can be written to support any printer backend.
+
+An example of this is the [inventree-brother-plugin](https://github.com/inventree/inventree-brother-plugin) which provides native support for the Brother QL and PT series of networked label printers.
+
+### Web Integration
+
+If label printing plugins are enabled, they are able to be used directly from the InvenTree web interface:
+
+{% with id="label_print", url="plugin/print_label_select_plugin.png", description="Print label via plugin" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### App Integration
+
+Label printing plugins also allow direct printing of labels via the [mobile app](../../app/stock.md#print-label)
+
+## Implementation
+
+Plugins which implement the `LabelPrintingMixin` mixin class must provide a `print_label` function:
+
+```python
+from dummy_printer import printer_backend
+
+class MyLabelPrinter(LabelPrintingMixin, IntegrationPluginBase):
+    """
+    A simple example plugin which provides support for a dummy printer.
+
+    A more complex plugin would communicate with an actual printer!
+    """
+
+    PLUGIN_NAME = "MyLabelPrinter"
+    PLUGIN_SLUG = "mylabel"
+    PLUGIN_TITLE = "A dummy printer"
+
+    def print_label(self, label):
+        """
+        Send the label to the printer
+        
+        Arguments:
+            label: A PIL (pillow) Image file
+        """
+
+        printer_backend.print(label)
+```
+
+

mkdocs.yml

@@ -109,20 +109,21 @@ nav:
     - Email: settings/email.md
     - Background Tasks: settings/tasks.md
   - Extend:
-    - API: extend/api.md
-    - Python Interface: extend/python.md
     - Plugins:
       - Overview: extend/plugins.md
-      - How to plugin: extend/how_to_plugin.md
+      - How To: extend/how_to_plugin.md
       - Action Mixin: extend/plugins/action.md
       - API Mixin: extend/plugins/api.md
       - App Mixin: extend/plugins/app.md
       - Barcode Mixin: extend/plugins/barcode.md
       - Event Mixin: extend/plugins/event.md
+      - Label Printing Mixin: extend/plugins/label.md
       - Navigation Mixin: extend/plugins/navigation.md
       - Schedule Mixin: extend/plugins/schedule.md
       - Settings Mixin: extend/plugins/settings.md
       - URL Mixin: extend/plugins/urls.md
+    - API: extend/api.md
+    - Python Interface: extend/python.md
     - Themes: extend/themes.md
     - Third-Party: extend/integrate.md
   - App: