From 3def121be2342f455f0dfae5dfc3d89585a82dd2 Mon Sep 17 00:00:00 2001 From: Oliver Date: Sat, 23 Jul 2022 22:40:05 +1000 Subject: [PATCH] Plugin external dir (#322) * Additional information on plugin configuration options * Better information on plugin installation * Update label printing docs * Rearrange plugin menu * More menu tweaks * Fix links to app images --- docs/app/stock.md | 4 +-- docs/extend/plugins.md | 22 --------------- docs/extend/plugins/install.md | 51 ++++++++++++++++++++++++++++++++++ docs/extend/plugins/label.md | 19 ++++++++++--- docs/start/config.md | 11 +++++++- mkdocs.yml | 4 ++- 6 files changed, 81 insertions(+), 30 deletions(-) create mode 100644 docs/extend/plugins/install.md diff --git a/docs/app/stock.md b/docs/app/stock.md index 67738e3..bde3d35 100644 --- a/docs/app/stock.md +++ b/docs/app/stock.md @@ -154,11 +154,11 @@ This barcode can then be used to track the stock item. 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" %} +{% with id="label_print_1", url="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" %} +{% with id="label_print_2", url="stock_print_label_2.png", description="Print label via plugin" %} {% include 'app_img.html' %} {% endwith %} diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md index b2d4958..a980ed0 100644 --- a/docs/extend/plugins.md +++ b/docs/extend/plugins.md @@ -104,25 +104,3 @@ Supported mixin classes are: - [ScheduleMixin](./plugins/schedule.md) - [SettingsMixin](./plugins/settings.md) - [UrlsMixin](./plugins/urls.md) - -## Installing a Plugin - -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. - -### Builtin 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. - -### 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 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. - diff --git a/docs/extend/plugins/install.md b/docs/extend/plugins/install.md new file mode 100644 index 0000000..23d364b --- /dev/null +++ b/docs/extend/plugins/install.md @@ -0,0 +1,51 @@ +--- +title: Installing Plugins +--- + + +## Installing a Plugin + +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. + +### 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 then installed from this file by simply running the command `invoke plugins`. + +Installation via PIP (using the *plugins.txt* file) provides a number of advantages: + +- Any required secondary packages are installed automatically +- You can update plugins simply by specifying version numbers in *plugins.txt* +- Migrating plugins between systems is simplified +- You can install plugins via any source supported by PIP + +!!! 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. + + +### Builtin 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`. + +!!! info "Debug Only" + The sample plugins 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). + +!!! info "Git Tracking" + The `src/InvenTree/plugins/` directory is excluded from Git version tracking - any plugin files here will be hidden from Git + +!!! warning "Not Recommended For Production" + Loading plugins via the local *plugins* directory is not recommended for production. If you cannot use PIP installation (above), specify a custom plugin directory (below). + +### Custom Directory + +If you wish to install plugins from local source, rather than PIP, it is better to place your plugins in a directory outside the InvenTree source directory. + +To achieve this, set the `INVENTREE_PLUGIN_DIR` environment variable to the directory where locally sourced plugins are located. Refer to the [configuration options](../../start/config.md#plugin-options) for further information. + +!!! info "Docker" + When running InvenTree in docker, a *plugins* directory is automatically created in the mounted data volume. Any plugins can be placed there, and will be automatically loaded when the server is started. diff --git a/docs/extend/plugins/label.md b/docs/extend/plugins/label.md index ecbacbd..ebe30e9 100644 --- a/docs/extend/plugins/label.md +++ b/docs/extend/plugins/label.md @@ -38,18 +38,29 @@ class MyLabelPrinter(LabelPrintingMixin, InvenTreePlugin): SLUG = "mylabel" TITLE = "A dummy printer" - def print_label(self, label, **kwargs): + def print_label(self, **kwargs): """ Send the label to the printer - Arguments: - label: A PIL (pillow) Image file + kwargs: + pdf_data: An in-memory PDF file of the label + png_file: An in-memory PIL (pillow) Image file of the label + filename: The filename of the printed label (if applicable) + label_instance: The Label model instance + width: width of the label (in mm) + height: height of the label (in mm) + user: The user who printed this label """ width = kwargs['width'] height = kwargs['height'] - printer_backend.print(label, w=width, h=height) + # This dummy printer supports printing of raw image files + printer_backend.print(png_file, w=width, h=height) ``` +### Available Data +The *label* data are supplied to the plugin in both `PDF` and `PNG` formats. This provides compatibility with a great range of label printers "out of the box". Conversion to other formats, if required, is left as an exercise for the plugin developer. + +Other arguments provided to the `print_label` function are documented in the code sample above. diff --git a/docs/start/config.md b/docs/start/config.md index 52c837d..f311b95 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -46,7 +46,6 @@ The following basic options are available: | --- | --- | --- | --- | | INVENTREE_DEBUG | debug | Enable debug mode | True | | INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | -| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False | ## Administrator Account @@ -181,6 +180,16 @@ If you want to remove the InvenTree branding as far as possible from your end-us !!! info "Custom Logo Path" The provided *custom logo* path must be specified *relative* to the location of thr `/media/` directory. +## Plugin Options + +The following [plugin](../extend/plugins.md) configuration options are available: + +| Environment Variable | Settings File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False | +| INVENTREE_PLUGIN_FILE | *N/A* | Location of plugin installation file | `./InvenTree/plugins.txt` | +| INVENTREE_PLUGIN_DIR | *N/A* | Location of external plugin directory | *Not set* | + ## Other Options ### Middleware diff --git a/mkdocs.yml b/mkdocs.yml index 205c5fb..ca18f75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,7 +127,9 @@ nav: - Extend: - Plugins: - Overview: extend/plugins.md - - How To: extend/how_to_plugin.md + - Installation: extend/plugins/install.md + - Developing a Plugin: extend/how_to_plugin.md + - Plugin Mixins: - Action Mixin: extend/plugins/action.md - API Mixin: extend/plugins/api.md - App Mixin: extend/plugins/app.md