Reference (#433)

* Adds page documenting reference strings

* Cleanup existing reference field documentation

docs/build/build.md

@@ -42,9 +42,7 @@ To navigate to the Build Order display, select *Build* from the main navigation
 
 ### Build Order Reference
 
-{% with prefix="BO-", label="Build Order" %}
-{% include "reference.html" %}
-{% endwith %}
+Each Build Order is uniquely identified by its *Reference* field. Read more about [reference fields](../settings/reference.md).
 
 ### Build Parameters
 

docs/buy/po.md

@@ -14,9 +14,7 @@ To access the purchase order page, click on the <span class="badge inventree nav
 
 ### Purchase Order Reference
 
-{% with prefix="PO-", label="Purchase Order" %}
-{% include "reference.html" %}
-{% endwith %}
+Each Purchase Order is uniquely identified by its *Reference* field. Read more about [reference fields](../settings/reference.md).
 
 ### Create Purchase Order
 

docs/sell/so.md

@@ -14,10 +14,7 @@ To access the sales order page, click on the <span class="badge inventree nav ma
 
 ### Sales Order Reference
 
-{% with prefix="SO-", label="Sales Order" %}
-{% include "reference.html" %}
-{% endwith %}
-
+Each Sales Order is uniquely identified by its *Reference* field. Read more about [reference fields](../settings/reference.md).
 
 ### Create Sales Order
 

docs/settings/reference.md

@@ -0,0 +1,50 @@
+---
+title: Reference Patterns
+---
+
+## Reference Patterns
+
+InvenTree contains a number of data models which require a *unique* reference field (such as [Purchase Orders](../buy/po.md)). In addition to being *unique* these reference values must conform to a specific *pattern* (which can be defined by the user). Defined reference patterns also make it simple for the user to control how references are generated.
+
+### Default Patterns
+
+Out of the box, InvenTree defines a standard "pattern" for each type of reference (which can be edited via the InvenTree [settings interface](./global.md)).
+
+| Model Type | Default Pattern | Example Output |
+| --- | --- | --- |
+| Purchase Order | `{% raw %}PO-{ref:04d}{% endraw %}` | PO-0001 |
+| Sales Order | `{% raw %}SO-{ref:04d}{% endraw %}` | SO-0123 |
+| Build Order | `{% raw %}BO-{ref:04d}{% endraw %}` | BO-1234 |
+
+### Pattern Requirements
+
+Patterns can contain a mixture of literal strings, named variable blocks, and wildcard characters:
+
+- The pattern **must** contain a single `{% raw %}{ref}{% endraw %}` variable - this is the required sequential part of the pattern
+- A `?` (question mark) character is treated as a wildcard which will match any character
+- A `#` (hash) character is treated as a wildcard which will match any digit `0-9`
+- Any other characters will be matched literally
+
+### Variables
+
+When building a reference, the following variables are available for use:
+
+| Variable | Description |
+| --- | --- |
+| `{% raw %}{ref}{% endraw %}` | Incrementing portion of the reference (**required*)). Determines which part of the reference field auto-increments |
+| `{% raw %}{date}{% endraw %}` | The current date / time. This is a [Python datetime object](https://docs.python.org/3/library/datetime.html#datetime.datetime.now) |
+
+The reference field pattern uses <a href="https://www.w3schools.com/python/ref_string_format.asp">Python string formatting</a> for value substitution.
+
+!!! tip "Date Formatting"
+    The `{% raw %}{date}{% endraw %}` variable can be formatted using the [Python Format Codes](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior).
+
+#### Substitution Examples
+
+Some examples below demonstrate how the variable substitution can be implemented:
+
+| Pattern | Description | Example Output |
+| --- | --- | --- |
+| `{% raw %}PO-{ref}{% endraw %}` | Render the *reference* variable without any custom formatting | PO-123 |
+| `{% raw %}PO-{ref:05d}{% endraw %}` | Render the *reference* variable as a 5-digit decimal number | PO-00123 |
+| `{% raw %}PO-{ref:05d}-{date:%Y-%M-%d}{% endraw %}` | Render the *date* variable in isoformat | PO-00123-2023-01-17 |