Reference docs (#308)

* Add information on build order reference

* Add reference field description for purchase order

* Add reference information for SalesOrder

* Updated images for build orders

* Update settings information

* Add note regarding python string formatting

* Add some more screenshots

* Improved BOM documentation

* Improve BOM documentation further

* Split  "BOM Export" onto separate page

* Rearrange docs pages

* Add image to fill TODO entry

* Split out part scheduling page

_includes/reference.html

@@ -0,0 +1,42 @@
+Each {{ label }} is uniquely identified by a <strong>Reference</strong> field.
+
+<h4>Reference Pattern</h4>
+<div class='admonition info'>
+    <!-- TODO: Delete this admonition block after 0.9.0 release -->
+    <p class='admonition-title'>New in v0.8.0</p>
+    <p>
+        Reference patterns were introduced in version 0.8.0. Users upgrading from an older version may find that the reference fields behave slightly differently than previous versions.
+    </p>
+</div>
+<p>
+    The {{ label }} <em>reference</em> field must conform to a (configurable) pattern, allowing users to define a standard for identifying individual orders.<br>
+    In addition to being used ensure the reference fields conform to a standard format, the reference pattern is also used to automatically generate sequential reference values.
+</p>
+<p>
+    The default pattern for the {{ label }} reference pattern is <code>{{ prefix }}{ref:04d}</code>.<br>
+    This will generate a sequence of reference values like:
+    
+    <ul>
+        <li>{{ prefix }}0001</li>
+        <li>{{ prefix }}0002</li>
+        <li>{{ prefix }}0003</li>
+    </ul>
+    
+    The {{ label }} reference pattern can be configured to generate a different reference sequence as required.
+</p>
+<p>
+    The {{ label }} pattern is implemented as follows:
+    <ul>
+        <li>The pattern must specify a single <code>{ref}</code> block - this is the <em>required</em> sequential portion of the pattern.</li>
+        <li>A <code>?</code> character is treated as a wildcard which will match any character.</li>
+        <li>A <code>#</code> character is treated as a wildcard which will match any number.</li>
+        <li>Any other characters will be matched literally.</li>
+    </ul>
+</p>
+
+<div class='admonition info'>
+    <p class='admonition-title'>Reference Formatting</p>
+    <p>
+        The reference field pattern uses <a href="https://www.w3schools.com/python/ref_string_format.asp">Python string formatting</a> for value substitution.
+    </p>
+</div>

docs/build/bom.md

@@ -98,55 +98,10 @@ The `Edit BOM Item Substitutes` form will be displayed:
 
 Select a part in the list and click on "Add Substitute" button to confirm.
 
-### Upload BOM
-
-Uploading a BOM to InvenTree is a three steps process:
-
-1. upload BOM file
-0. select matching InvenTree fields
-0. select matching InvenTree parts.
-
-To upload a BOM file, navigate to the part/assembly detail page then click on the "BOM" tab. On top of the tab view, click on the <span class='fas fa-edit'></span> icon then, after the page reloads, click on the <span class='fas fa-file-upload'></span> icon.
-
-The following view will load:
-{% with id="bom_upload_file", url="build/bom_upload_file.png", description="BOM Upload View" %}
-{% include 'img.html' %}
-{% endwith %}
-
-#### Upload BOM File
-
-Click on the "Choose File" button, select your BOM file when prompted then click on the "Upload File" button.
-
-!!! info "BOM Formats"
-	The following BOM file formats are supported: CSV, TSV, XLS, XLSX, JSON and YAML
-
-#### Select Fields
-
-Once the BOM file is uploaded, the following view will load:
-{% with id="bom_select_fields", url="build/bom_select_fields.png", description="Select Fields View" %}
-{% include 'img.html' %}
-{% endwith %}
-
-InvenTree will attempt to automatically match the BOM file columns with InvenTree part fields. `Part_Name` is a **required** field for the upload process and moving on to the next step. Specifying the `Part_IPN` field matching is very powerful as it allows to create direct pointers to InvenTree parts.
-
-Once you have selected the corresponding InvenTree fields, click on the "Submit Selections" button to move on to the next step.
-
-#### Select Parts
-
-Once the BOM file columns and InvenTree fields are correctly matched, the following view will load:
-{% with id="bom_select_parts", url="build/bom_select_parts.png", description="Select Parts View" %}
-{% include 'img.html' %}
-{% endwith %}
-
-InvenTree automatically tries to match parts from the BOM file with parts in its database. For parts that are found in InvenTree's database, the `Select Part` field selection will automatically point to the matching database part.
-
-In this view, you can also edit the parts `Reference` and `Quantity` fields.
-
-Once you have selected the corresponding InvenTree parts, click on the "Submit BOM" button to complete the BOM upload process.
 
 ### Validate BOM
 
-After [adding BOM items manually](#add-bom-item) or [uploading a BOM file](#upload-bom), you should see the following view:
+After [adding BOM items manually](#add-bom-item) or [uploading a BOM file](./bom_import.md), you should see the following view:
 {% with id="bom_invalid", url="build/bom_invalid.png", description="Invalid BOM View" %}
 {% include 'img.html' %}
 {% endwith %}
@@ -155,8 +110,20 @@ The first message in the red box `The BOM for PCBA TEST has changed, and must be
 
 To process with BOM validation, click on the <span class='fas fa-clipboard-check'></span> icon and the `Validate BOM` form will be displayed. Click one the "Validate" switch then click on <span class="badge inventree confirm">Submit</span>
 
-Voilà, this Bill of Materials is validated <span class='far fa-smile'></span>
-
 {% with id="bom_valid", url="build/bom_valid.png", description="Valid BOM View" %}
 {% include 'img.html' %}
 {% endwith %}
+
+## Multi Level BOMs
+
+Multi-level (hierarchical) BOMs are natively supported by InvenTree. A Bill of Materials (BOM) can contain sub-assemblies which themselves have a defined BOM. This can continue for an unlimted number of levels.
+
+When viewing a BOM table, sub-assemblies are not loaded by default, but can be loaded "on demand" by pressing the <span class='fas fa-sync-alt'></span> icon associated with the particular subassembly:
+
+{% with id="bom_flat", url="build/bom_flat.png", description="Flat BOM Table" %}
+{% include 'img.html' %}
+{% endwith %}
+
+{% with id="bom_expanded", url="build/bom_expanded.png", description="Expanded BOM Table" %}
+{% include 'img.html' %}
+{% endwith %}

docs/build/bom_export.md

@@ -0,0 +1,44 @@
+---
+title: BOM Export
+---
+
+## Exporting BOM Data
+
+
+BOM data can be exported for any given assembly by selecting the *Export BOM* action from the BOM actions menu.
+
+You will be presented with the *Export BOM* options dialog, shown below:
+
+{% with id="bom_export", url="build/bom_export.png", description="Export BOM Data" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### BOM Export Options
+
+**Format**
+
+Select the file format for the exported BOM data
+
+**Multi Level BOM**
+
+If selected, BOM data will be included for any subassemblies. If not selected, only top level (flat) BOM data will be exported.
+
+**Levels**
+
+Define the maximum level of data to export for subassemblies. If set to zero, all levels of subassembly data will be exported.
+
+**Include Parameter Data**
+
+Include part parameter data in the exported dataset.
+
+**Include Stock Data**
+
+Include part stock level information in the exported dataset.
+
+**Include Manufacturer Data**
+
+Include part manufacturer information in the exported dataset.
+
+**Include Supplier Data**
+
+Include part supplier information in the exported dataset.

docs/build/bom_import.md

@@ -0,0 +1,49 @@
+---
+title: BOM Import
+---
+
+## Importing BOM Data
+
+Uploading a BOM to InvenTree is a three steps process:
+
+1. Upload BOM file
+0. Select matching InvenTree fields
+0. Select matching InvenTree parts.
+
+To upload a BOM file, navigate to the part/assembly detail page then click on the "BOM" tab. On top of the tab view, click on the <span class='fas fa-edit'></span> icon then, after the page reloads, click on the <span class='fas fa-file-upload'></span> icon.
+
+The following view will load:
+{% with id="bom_upload_file", url="build/bom_upload_file.png", description="BOM Upload View" %}
+{% include 'img.html' %}
+{% endwith %}
+
+#### Upload BOM File
+
+Click on the "Choose File" button, select your BOM file when prompted then click on the "Upload File" button.
+
+!!! info "BOM Formats"
+	The following BOM file formats are supported: CSV, TSV, XLS, XLSX, JSON and YAML
+
+#### Select Fields
+
+Once the BOM file is uploaded, the following view will load:
+{% with id="bom_select_fields", url="build/bom_select_fields.png", description="Select Fields View" %}
+{% include 'img.html' %}
+{% endwith %}
+
+InvenTree will attempt to automatically match the BOM file columns with InvenTree part fields. `Part_Name` is a **required** field for the upload process and moving on to the next step. Specifying the `Part_IPN` field matching is very powerful as it allows to create direct pointers to InvenTree parts.
+
+Once you have selected the corresponding InvenTree fields, click on the "Submit Selections" button to move on to the next step.
+
+#### Select Parts
+
+Once the BOM file columns and InvenTree fields are correctly matched, the following view will load:
+{% with id="bom_select_parts", url="build/bom_select_parts.png", description="Select Parts View" %}
+{% include 'img.html' %}
+{% endwith %}
+
+InvenTree automatically tries to match parts from the BOM file with parts in its database. For parts that are found in InvenTree's database, the `Select Part` field selection will automatically point to the matching database part.
+
+In this view, you can also edit the parts `Reference` and `Quantity` fields.
+
+Once you have selected the corresponding InvenTree parts, click on the "Submit BOM" button to complete the BOM upload process.

docs/build/build.md

@@ -26,12 +26,26 @@ To navigate to the Build Order display, select *Build* from the main navigation
 {% include "img.html" %}
 {% endwith %}
 
+#### Tree Vieww
+
+*Tree View* also provides a tabulated view of Build Orders. Orders are displayed in a hierarchical manner, showing any parent / child relationships between different build orders. 
+
+{% with id="build_tree", url="build/build_tree.png", description="Build Tree" %}
+{% include "img.html" %}
+{% endwith %}
+
 #### Calendar View
 
 *Calendar View* shows a calendar display with upcoming build orders, based on the various dates specified for each build.
 
 ## Build Order Details
 
+### Build Order Reference
+
+{% with prefix="BO-", label="Build Order" %}
+{% include "reference.html" %}
+{% endwith %}
+
 ### Build Parameters
 
 The following parameters are available for each Build Order, and can be edited by the user:

docs/buy/manufacturer.md

@@ -8,7 +8,11 @@ A manufacturer is an external **producer** of parts and raw materials.
 
 To access the manufacturer page, click on the <span class="badge inventree nav main"><span class='fas fa-shopping-cart'></span> Buy</span> navigation tab and click on <span class="badge inventree nav main"><span class='fas fa-industry'></span> Manufacturers</span> option in the dropdown list.
 
-!!! warning
+{% with id="manufacturer_list", url="buy/manufacturer_list.png", description="Manufacturer List" %}
+{% include "img.html" %}
+{% endwith %}
+
+!!! info
 	**Viewing**, **adding**, **editing** and **deleting** manufacturers require the corresponding [Purchase Orders user permissions](../settings/permissions.md)
 
 ### Add Manufacturer

docs/buy/po.md

@@ -8,6 +8,16 @@ Purchase orders allow to track which parts are bought from suppliers and manufac
 
 To access the purchase order page, click on the <span class="badge inventree nav main"><span class='fas fa-shopping-cart'></span> Buy</span> navigation tab and click on <span class="badge inventree nav main"><span class='fas fa-list'></span> Purchase Orders</span> option in the dropdown list.
 
+{% with id="purchase_order_list", url="buy/po_list.png", description="Purchase Order List" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Purchase Order Reference
+
+{% with prefix="PO-", label="Purchase Order" %}
+{% include "reference.html" %}
+{% endwith %}
+
 ### Create Purchase Order
 
 Once the purchase order page is loaded, click on <span class="badge inventree add"><span class='fas fa-plus-circle'></span> New Purchase Order</span> which opens the "Create Purchase Order" form.

docs/buy/supplier.md

@@ -8,7 +8,11 @@ A supplier is an external **vendor** of parts and raw materials.
 
 To access the supplier page, click on the <span class="badge inventree nav main"><span class='fas fa-shopping-cart'></span> Buy</span> navigation tab and click on <span class="badge inventree nav main"><span class='fas fa-building'></span> Suppliers</span> option in the dropdown list.
 
-!!! warning
+{% with id="supplier_list", url="buy/supplier_list.png", description="Supplier List" %}
+{% include "img.html" %}
+{% endwith %}
+
+!!! info
 	**Viewing**, **adding**, **editing** and **deleting** suppliers require the corresponding [Purchase Orders user permissions](../settings/permissions.md)
 
 ### Add Supplier

docs/part/scheduling.md

@@ -0,0 +1,34 @@
+---
+title: Part Scheduling
+---
+
+## Part Scheduling
+
+
+The *Scheduling* tab provides an overview of the *predicted* future availabile quantity of a particular part.
+
+The *Scheduling* tab displays a chart of estimated future part stock levels. It begins at the current date, with the current stock level. It then projects into the "future", taking information from:
+
+#### Incoming Stock
+
+- **Purchase Orders** - Incoming goods will increase stock levels
+- **Build Orders** - Completed build outputs will increase stock levels
+
+#### Outgoing Stock
+
+- **Sales Orders** - Outgoing stock items will reduce stock levels
+- **Build Orders** - Allocated stock items will reduce stock levels
+
+#### Caveats
+
+The scheduling information only works as an adequate predictor of future stock quantity if there is sufficient information available in the database.
+
+In particular, stock movements due to orders (Purchase Orders / Sales Orders / Build Orders) will only be counted in the scheduling *if a target date is set for the order*. If the order does not have a target date set, we cannot know *when* (in the future) the stock levels will be adjusted. Thus, orders without target date information do not contribute to the scheduling information.
+
+Additionally, any orders with a target date in the "past" are also ignored for the purpose of part scheduling.
+
+Finally, any unexpected or unscheduled stock operations which are not associated with future orders cannot be predicted or displayed in the scheduling tab.
+
+{% with id="scheduling", url="part/scheduling.png", description="Part Scheduling View" %}
+{% include 'img.html' %}
+{% endwith %}

docs/part/trackable.md

@@ -35,4 +35,4 @@ For example:
 
 ## Build Orders
 
-Build orders have some extra requirements when either building a trackable part, or using parts in the Bill of Materials which are themselves trackable.
+[Build orders](../build/build.md) have some extra requirements when either building a trackable part, or using parts in the Bill of Materials which are themselves trackable.

docs/part/views.md

@@ -124,33 +124,7 @@ The *Sales Orders* tab shows a list of the sales orders for this part. It provid
 
 ### Scheduling
 
-The *Scheduling* tab provides an overview of the *predicted* future availabile quantity of a particular part.
-
-The *Scheduling* tab displays a chart of estimated future part stock levels. It begins at the current date, with the current stock level. It then projects into the "future", taking information from:
-
-#### Incoming Stock
-
-- **Purchase Orders** - Incoming goods will increase stock levels
-- **Build Orders** - Completed build outputs will increase stock levels
-
-#### Outgoing Stock
-
-- **Sales Orders** - Outgoing stock items will reduce stock levels
-- **Build Orders** - Allocated stock items will reduce stock levels
-
-#### Caveats
-
-The scheduling information only works as an adequate predictor of future stock quantity if there is sufficient information available in the database.
-
-In particular, stock movements due to orders (Purchase Orders / Sales Orders / Build Orders) will only be counted in the scheduling *if a target date is set for the order*. If the order does not have a target date set, we cannot know *when* (in the future) the stock levels will be adjusted. Thus, orders without target date information do not contribute to the scheduling information.
-
-Additionally, any orders with a target date in the "past" are also ignored for the purpose of part scheduling.
-
-Finally, any unexpected or unscheduled stock operations which are not associated with future orders cannot be predicted or displayed in the scheduling tab.
-
-{% with id="scheduling", url="part/scheduling.png", description="Part Scheduling View" %}
-{% include 'img.html' %}
-{% endwith %}
+The *Scheduling* tab provides an overview of the *predicted* future availability of a particular part. Refer to the [scheduling documentation](./scheduling.md) for further information.
 
 ### Tests
 

docs/sell/so.md

@@ -8,6 +8,17 @@ Sales orders allow to track which stock items are sold to customers, therefore c
 
 To access the sales order page, click on the <span class="badge inventree nav main"><span class='fas fa-truck'></span> Sell</span> navigation tab and click on <span class="badge inventree nav main"><span class='fas fa-list'></span> Sales Orders</span> option in the dropdown list.
 
+{% with id="sales_order_list", url="sell/so_list.png", description="Sales Order List" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Sales Order Reference
+
+{% with prefix="SO-", label="Sales Order" %}
+{% include "reference.html" %}
+{% endwith %}
+
+
 ### Create Sales Order
 
 Once the sales order page is loaded, click on <span class="badge inventree add"><span class='fas fa-plus-circle'></span> New Sales Order</span> which opens the "Create Sales Order" form.

docs/settings/global.md

@@ -160,8 +160,7 @@ Options for build orders
 
 | Setting | Type | Description | Default |
 | --- | --- | --- | --- |
-| Reference Prefix | String | Prefix for build order reference | BO |
-| Reference Regex | String | Regular expression pattern for build order reference | *blank* |
+| Reference Pattern | String | Pattern for defining Build Order reference values | {% raw %}BO-{ref:04d}{% endraw %} |
 
 ### Purchase Orders
 
@@ -169,7 +168,7 @@ Options for purchase orders
 
 | Setting | Type | Description | Default |
 | --- | --- | --- | --- |
-| Reference Prefix | String | Prefix for purchase order reference | PO |
+| Reference Pattern | String | Pattern for defining Purchase Order reference values | {% raw %}PO-{ref:04d}{% endraw %} |
 
 ### Sales orders
 
@@ -177,7 +176,7 @@ Options for sales orders
 
 | Setting | Type | Description | Default |
 | --- | --- | --- | --- |
-| Reference Prefix | String | Prefix for sales order reference | SO |
+| Reference Pattern | String | Pattern for defining Sales Order reference values | {% raw %}SO-{ref:04d}{% endraw %} |
 
 ### Plugin Settings
 

docs/stock/test.md

@@ -8,8 +8,9 @@ Stock items which are associated with a *trackable* part can have associated tes
 
 The master "Part" record for the stock item can define multiple [test templates](../part/test.md), against which test data can be uploaded. Additionally, arbitrary test information can be assigned to the stock item.
 
-!!! missing "TODO"
-	Include pictures of the Test Results tab
+{% with id="stock_test_results", url="stock/test_results.png", description="Stock Item Test Results" %}
+{% include 'img.html' %}
+{% endwith %}
 
 ### Test Result Fields
 

mkdocs.yml

@@ -77,6 +77,7 @@ nav:
     - Templates: part/template.md
     - Tests: part/test.md
     - Pricing: part/pricing.md
+    - Scheduling: part/scheduling.md
     - Notifications: part/notification.md
   - Stock:
     - Stock Items: stock/stock.md
@@ -87,8 +88,10 @@ nav:
     - Test Results: stock/test.md
   - Build:
     - Build Orders: build/build.md
-    - Bill of Materials: build/bom.md
     - Allocating Stock: build/allocate.md
+    - Bill of Materials: build/bom.md
+    - Importing BOM Data: build/bom_import.md
+    - Exporting BOM Data: build/bom_export.md
   - Buy:
     - Suppliers: buy/supplier.md
     - Manufacturers: buy/manufacturer.md