Merge branch 'master' of https://github.com/inventree/inventree-docs

docs/releases/0.1.5.md

@@ -21,9 +21,39 @@ Refer to the [build documentation](../../build/build/#overdue-builds) for more i
 
 [#1177](https://github.com/inventree/InvenTree/pull/1177) introduces the concept of *Target Date* for a Sales Order. This is the intended shipment date for the order. If the date is reached but the order is not yet complete, the order is considered *overdue*.
 
+### Target Date for Purchase Order
+
+[#1232](https://github.com/inventree/InvenTree/pull/1232) introduces the concept *Target Date* for a Purchase Order. This is the expected delivery date for the order. If the date is reached but the order is not yet complete, the order is considered *overdue*.
+
+### Stock Item Expiry
+
+[#1202](https://github.com/inventree/InvenTree/pull/1202) introduces the concept of an *Expiry Date* for Stock Items. For further information, refer to the [expiry documentation](../../stock/expiry).
+
+### Calendar Views
+
+[#1208](https://github.com/inventree/InvenTree/pull/1208) adds interactive calendar displays to assist with order scheduling. Calendar displays are available for:
+
+- Build Orders
+- Purchase Orders
+- Sales Orders
+
+### Improved Label Printing
+
+[#1212](https://github.com/inventree/InvenTree/pull/1212) significantly improves the existing label printing functionality. Documentation for the new label printing system [can be found here](../../report/labels).
+
+### Improved Permission System
+
+[#1221](https://github.com/inventree/InvenTree/pull/1221) adds new permission roles as follows:
+
+- **Part** role split into *Part* and *Part Category* roles
+- **Stock** role spit into *Stock Item* and *Stock Location* roles 
+
+
 ## Major Bug Fixes
 
 | PR | Description |
 | --- | --- |
 | [#1144](https://github.com/inventree/InvenTree/pull/1144) | Fixes infinite loop recursion when displaying BOM table |
 | [#1175](https://github.com/inventree/InvenTree/pull/1175) | Fixes display of buttons in particular StockItem tab |
+| [#1196](https://github.com/inventree/InvenTree/pull/1195) | Fixes issue where forms incorrectly required date fields to be filled |
+| [#1197](https://github.com/inventree/InvenTree/pull/1197) | Fixes variable scope issue which caused problems with BOM creation |

docs/report/labels.md

@@ -4,55 +4,188 @@ title: Custom Labels
 
 ## Custom Labels
 
-InvenTree supports printing of custom template-based labels, using the [blabel](https://github.com/Edinburgh-Genome-Foundry/blabel) plugin for Python.
+InvenTree supports printing of custom template-based labels, using the [blabel](https://github.com/Edinburgh-Genome-Foundry/blabel) Python library.
 
 Custom labels can be generated using simple HTML templates, with support for QR-codes, and conditional formatting using the Jinja template engine.
 
 !!! info "Documentation"
-	Refer to the blabel documentation for further information
+	Refer to the [blabel documentation](https://edinburgh-genome-foundry.github.io/blabel/) for further information, and examples of the available features
 
-### Creating Labels
+Simple (generic) label templates are supplied 'out of the box' with InvenTree - however support is provided for generation of extremely specific custom labels, to meet any particular requirement.
 
-!!! missing "TODO"
-	This section requires further work
+## Label Templates
+
+Label templates are written using a mixture of [HTML](https://www.w3schools.com/html/) and [CSS](https://www.w3schools.com/css). The blabel library is based on [weasyprint](https://weasyprint.org/), which supports a *subset* of HTML and CSS features. In addition to supporting HTML and CSS formatting, the label templates support the Jinja templating engine, allowing conditional formatting of the label data.
+
+A label template is a single `.html` file which is uploaded to the InvenTree server by the user.
+
+Below is a reasonably simple example of a label template which demostrates much of the available functionality. The template code shown below will produce the following label:
+
+{% with id="label_example", url="report/label_example.png", description="Example label" %}
+{% include 'img.html' %}
+{% endwith %}
+
+```html
+{% raw %}
+<style>
+    @page {
+        width: 75mm;
+        height: 24mm;
+        padding: 1mm;
+    }
+    
+    .location {
+        padding: 5px;
+        font-weight: bold;
+        font-family: Arial, Helvetica, sans-serif;
+        height: 100%;
+        vertical-align: middle;
+        float: right;
+        display: inline;
+        font-size: 125%;
+        position: absolute;
+        top: 0mm;
+        left: 23mm;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+    
+    .qr {
+        margin: 2px;
+        width: 22mm;
+        height: 22mm;
+    }
+    
+</style>
+    
+<img class='qr' src="{{ label_tools.qr_code(location.barcode) }}"/>
+
+<div class='location'>
+	{{ location.name }}
+	<br>
+	<br>
+	<hr>
+	Location ID: {{ location.id }}
+	</div>
+</div>
+{% endraw %}
+```
+
+Each significant component of the example template above are described in the sections below:
 
 ### Stylesheet
 
-!!! missing "TODO"
-	This section requires further work
+The stylesheet defines the *style* of the label, and is enclosed within the `<style>...</style>` tags. The stylesheet supports any of the CSS features which are supported natively by weasyprint.
+
+Some points of note:
+
+- The `@page` directive specifies the size of the label, and global margins.
+- Normal per-class and per-element styling is supported
+- Absolute positioning of elements is supported via the `position` CSS directive
+- If text is too long to fit on a given label, the `text-overflow` directive can be used
 
 ### Context Data
 
-Each label template is supplied with *context data* (variables) which can be used to display information based on the context in which the label is printed.
+Each label template is supplied with *context data* (variables) which can be used to display information based on the context in which the label is printed. Variables supplied as context objects can be easily rendered to the label using jinja templating syntax.
 
-!!! missing "TODO"
-	This section requires further work
+For example, if a StockLocation object is supplied to the label as the variable `location`, it is trivially simple to render the data to the label:
+
+```html
+{% raw %}
+Location ID: {{ location.id }}
+<br>
+Location Name: {{ location.name }}
+{% endraw %}
+```
 
 ### QR Codes
 
-!!! missing "TODO"
-	This section requires further work
+`blabel` supports barcodes and QR codes 'out of the box'. Passing data to render as a barcode or QR code is handled in the template file itself.
+
+Refer to the [blabel docs](https://edinburgh-genome-foundry.github.io/blabel/) for further information.
 
 ### Conditional Formatting
 
-!!! missing "TODO"
-	This section requires further work
+Conditional formatting of label data is also supported. Below is an example excerpt from a label which determines the content based on the supplied context variables:
 
-## Stock Labels
+```html
+{% raw %}
+{% if item.in_stock %}
+Quantity: {{ item.quantity }}
+{% else %}
+OUT OF STOCK
+{% endif %}
+{% endraw %}
+```
 
-!!! missing "TODO"
-	This section requires further work
+### Label Filters
+
+Each label template provides a set of programmable filters which can be used to determine the relevance of that particular label. It may be the case that a particular label template is only applicable if certain conditions are met.
+
+As an example, consider a label template for a StockItem. A user may wish to define a label which displays the firmware version of any items related to the Part with the IPN (Internal Part Number) `IPN123`. 
+
+To restrict the label accordingly, we could set the *filters* value to `part__IPN=IPN123`.
+
+### Built-In Templates
+    
+The InvenTree installation provides a number of simple *default* templates which can be used as a starting point for creating custom labels. These built-in templates can be disabled if they are not required.
+
+## Stock Item Labels
+
+Stock Item label templates are used to generate labels for individual Stock Items. 
+
+### Creating Stock Item Label Templates
+
+Stock Item label templates are added (and edited) via the admin interface.
+
+### Printing Stock Item Labels
+
+Stock Item labels can be printed using the following approaches:
+
+To print a single stock item from the Stock Item detail view, select the *Print Label* option as shown below:
+
+{% with id='item_label_single', url='report/label_stock_print_single.png', description='Print single stock item label' %}
+{% include 'img.html' %}
+{% endwith %}
+
+To print multiple stock items from the Stock table view, select the *Print Labels* option as shown below:
+
+{% with id='item_label_multiple', url='report/label_stock_print_multiple.png', description='Print multiple stock item labels' %}
+{% include 'img.html' %}
+{% endwith %}
 
 ### Context Data
 
-In addition to the global label context data, the following variables are made available to the StockItem label template:
+The following variables are made available to the StockItem label template:
 
-* item - *The StockItem object itself*
-* part - *The Part object which is referenced by the StockItem object*
-* name - *The `name` field of the Part object*
-* ipn - *The `IPN` field of the Part object*
-* quantity - *The `quantity` field of the StockItem object*
-* serial - *The `serial` field of the StockItem object*
-* uid - *The `uid` field of the StockItem object*
-* qr_data - *JSON data representing the StockItem object, useful for rendering to a QR code*
-* tests - *Dict object of TestResult data associated with the StockItem*
+| Variable | Description |
+| -------- | ----------- |
+| item | The StockItem object itself |
+| part | The Part object which is referenced by the StockItem object |
+| name | The `name` field of the associated Part object | 
+| ipn | The `IPN` field of the associated Part object |
+| quantity | The `quantity` field of the StockItem object |
+| serial | The `serial` field of the StockItem object |
+| uid | The `uid` field of the StockItem object |
+| tests | Dict object of TestResult data associated with the StockItem |
+
+## Stock Location Labels
+
+Stock Location label templates are used to generate labels for individual Stock Locations.
+
+### Creating Stock Location Label Templates
+
+Stock Location label templates are added (and edited) via the admin interface. 
+
+### Printing Stock Location Labels
+
+To print a single label from the Stock Location detail view, select the *Print Label* option.
+
+### Context Data
+
+The following variables are made available to the StockLocation label template:
+
+| Variable | Description |
+| -------- | ----------- |
+| location | The StockLocation object itself |

docs/start/install.md

@@ -108,6 +108,9 @@ Install invoke as follows:
 pip3 install invoke
 ```
 
+!!! warning "Invoke Version"
+	InvenTree requires invoke version 1.4.0 or newer. Some platforms may be shipped with older versions of invoke!
+
 To display a list of the available configuration scripts, run the following command:
 
 ```

docs/stock/expiry.md

@@ -0,0 +1,85 @@
+---
+title: Stock Expiry
+---
+
+## Stock Expiry
+
+InvenTree supports stock expiration dates, which allows individual stock items to be automatically marked as *expired* past a certain calendar date.
+
+The stock expiry feature is disabled by default, and must be enabled via the settings menu:
+
+{% with id="stock_expiry", url="stock/enable_stock_expiry.png", description="Enable stock expiry feature" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! info "Non Expiring Stock"
+    If a Stock Item is not expected to expire, 
+
+### Add Expiry Date
+
+When creating a new stock item, the expiry date can be manually set by the user. 
+
+{% with id="expiry_create", url="stock/expiry_date_create.png", description="Add expiry date" %}
+{% include 'img.html' %}
+{% endwith %}
+
+If an expiry date is defined for a particular stock item, it will be displayed on the detail page. If the expiry date has passed (and the stock item is *expired*) then this will also be indicated.
+
+{% with id="item_expired", url="stock/item_expired.png", description="Display expiry date" %}
+{% include 'img.html' %}
+{% endwith %}
+
+The expiry date can be adjusted in the stock item edit form.
+
+{% with id="expiry_edit", url="stock/expiry_date_edit.png", description="Edit expiry date" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Filter Expired Stock
+
+The various stock display tables can be filtered by *expired* status, and also display a column for the expiry date for each stock item.
+
+{% with id="stock_table_expiry", url="stock/stock_table_expiry.png", description="Filter by stock expiry" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Index Page
+
+If the stock expiry feature is enabled, expired stock are listed on the InvenTree home page, to provide visibility of expired stock to the users.
+
+## Part Expiry Time
+
+In addition to allowing manual configuration of expiry dates on a per-item basis, InvenTree also provides the ability to set a "default expiry time" for a particular Part. This expiry time (specified in *days*) is then used to automatically calculate the expiry date when creating a new Stock Item as an instance of the given Part.
+
+For example, if a Part has a default expiry time of 30 days, then any Stock Items created for that Part will automatically have their expiry date set to 30 days in the future.
+
+!!! info "Non Expiring Parts"
+    If a part is not expected to expire, set the default expiry time to 0 (zero) days.
+
+If a Part has a non-zero default expiry time, it will be displayed on the Part details page
+
+{% with id="part_expiry_display", url="stock/part_expiry_display.png", description="Part expiry" %}
+{% include 'img.html' %}
+{% endwith %}
+
+The Part expiry time can be altered using the Part editing form.
+
+{% with id="part_expiry_edit", url="stock/part_expiry.png", description="Edit part expiry" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## Sales Orders
+
+By default, expired Stock Items cannot be added to a Sales Order. This behavior can be adjusted using the *Sell Expired Stock* setting.
+
+{% with id="sell_expired", url="stock/sell_expired_stock.png", description="Sell expired stock" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## Build Orders
+
+By default, expires Stock Items cannot be added to a Build Order. This behaviour can be adjusted using the *Build Expired Stock* setting.
+
+{% with id="build_expired", url="stock/build_expired_stock.png", description="Build expired stock" %}
+{% include 'img.html' %}
+{% endwith %}

mkdocs.yml

@@ -57,6 +57,7 @@ nav:
     - Stock Items: stock/stock.md
     - Adjusting Stock: stock/adjust.md
     - Stocktake: stock/stocktake.md
+    - Stock Expiry: stock/expiry.md
     - Test Results: stock/test.md
   - Build:
     - Build Parts: build/build.md