Reference (#433)

* Adds page documenting reference strings

* Cleanup existing reference field documentation

_includes/reference.html

@@ -1,35 +0,0 @@
-Each {{ label }} is uniquely identified by a <strong>Reference</strong> field.
-
-<h4>Reference Pattern</h4>
-<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/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 |

mkdocs.yml

@@ -124,6 +124,7 @@ nav:
   - Admin:
     - Global Settings: settings/global.md
     - User Settings: settings/user.md
+    - Reference Patterns: settings/reference.md
     - Admin Interface: settings/admin.md
     - User Permissions: settings/permissions.md
     - Single Sign on: settings/SSO.md