Adds documentation for new "auto allocation" feature

_includes/config.yaml

@@ -154,6 +154,11 @@ static_root: '/home/inventree/data/static'
 # Use environment variable INVENTREE_LOGIN_ATTEMPTS
 #login_attempts: 5
 
+# Add new user on first startup
+#admin_user: admin
+#admin_email: info@example.com
+#admin_password: inventree
+
 # Permit custom authentication backends
 #authentication_backends:
 #  - 'django.contrib.auth.backends.ModelBackend'

docs/build/allocate.md

@@ -61,25 +61,20 @@ In each row, pressing the <span class='fas fa-plus'></span> icon expands the row
 {% include "img.html" %}
 {% endwith %}
 
-### Auto Allocation
-
-To speed up the allocation process, the *Auto Allocate* button can be used to allocate untracked stock items to the build. Automatic allocation of stock items does not work in every situation, as a number of criteria must be met.
+## Manual Stock Allocation
 
 For each line in the BOM, stock will be automatically allocated if one (and only one) stock item (for the referenced part) is found (within the specified *source location* for the build):
 
-!!! warning "Multiple Stock Items"
-    If multiple stock items are available, the InvenTree auto allocation system cannot make a determination about which stock item to allocate.
-
-Selecting *Auto Allocate* opens a dialog window which displays the stock items which will be allocated to the build during the auto allocation process:
+Selecting *Allocate Stock* opens a dialog window which displays the stock items which will be allocated to the build during the auto allocation process:
 
 {% with id="build_auto", url="build/build_auto_allocate.png", description="Auto allocate" %}
 {% include "img.html" %}
 {% endwith %}
 
-!!! info "Note"
-    Note here that the *SAM-M8Q-0-10* part can be automatically allocated as it only exists in a single stock location. However the other BOM line item exists in multiple locations, and thus cannot be automatically allocated
+Note here that there are two parts in the BOM which can be automatically allocated, as they only have a single corresponding StockItem available.
+However the other BOM line item exists in multiple locations, and thus cannot be automatically allocated. These will need to be manually selected by the user.
 
-### Manual Allocation
+### Row Allocation
 
 Stock can be manually allocated to the build as required, using the *Allocate stock* button available in each row of the allocation table
 
@@ -91,6 +86,34 @@ Stock allocations can be manually adjusted or deleted using the action buttons a
 
 The *Unallocate Stock* button can be used to remove all allocations of untracked stock items against the build order.
 
+## Automatic Stock Allocation
+
+To speed up the allocation process, the *Auto Allocate* button can be used to allocate untracked stock items to the build. Automatic allocation of stock items does not work in every situation, as a number of criteria must be met.
+
+The *Automatic Allocation* dialog is presented as shown below:
+
+{% with id="auto_allocate_dialog", url="build/auto_allocate_dialog.png", description="Automatic allocation dialog" %}
+{% include "img.html" %}
+{% endwith %}
+
+**Source Location**
+
+Select the master location where stock items are to be allocated from. Leave this input blank to allocate stock items from any available location.
+
+**Interchangeable Stock**
+
+Set this option to *True* to signal that stock items can be used interchangeably. This means that in the case where multiple stock items are available, the auto-allocation routine does not care which stock item it uses.
+
+!!! warning "Take Care"
+    If the *Interchangeable Stock* option is enabled, and there are multiple stock items available, the results of the automatic allocation algorithm may somewhat unexpected.
+
+!!! info "Example"
+    Let's say that we have 5 reels of our *C_100nF_0603* capacitor, each with 4,000 parts available. If we do not mind which of these reels the stock should be taken from, we enable the *Interchangeable Stock* option in the dialog above. In this case, the stock will be allocated from one of these reels, and eventually subtracted from stock when the build is completed. 
+
+**Substitute Stock**
+
+Set this option to *True* to allow substitute parts (as specifed by the BOM) to be allocated, if the primary parts are not available.
+
 ## Allocating Tracked Stock
 
 Allocation of tracked stock items is slightly more complex. Instead of being allocated against the *Build Order*, tracked stock items must be allocated against an individual *Build Output*.