Documentation integration (#4653)

* Add documentation under docs/ directory

* Add CI workflow for mkdocs configuration checking

* Add documentation issue template

* update pip-tools?

* Update .gitignore files

* Fix .gitignore rules

* Improve release notes page

* remove references to old repo

docs/docs/stock/adjust.md

@@ -0,0 +1,79 @@
+---
+title: Stock Adjustments
+---
+
+## Stock Adjustments
+
+InvenTree provides simple yet powerful management of stock levels. Multiple stock adjustment options are available, and each type of adjustment is automatically tracked to maintain a complete stock history.
+
+Stock adjustements can be accessed in any stock items table using the "Stock Options" dropdown entries:
+
+{% with id="stock_options", url="stock/stock_options.png", description="Stock Options" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Move Stock
+
+Multiple stock items can be moved to a new location in a single operation. Each item is moved to the selected location, and a stock tracking entry is added to the stock item history.
+
+{% with id="stock_move", url="stock/stock_move.png", description="Stock movement" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Add Stock
+
+Add parts to a stock item record - for example putting parts back into stock. The in-stock quantity for each selected item is increased by the given amount.
+
+{% with id="stock_add", url="stock/stock_add.png", description="Stock addition" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Remove Stock
+
+Remove parts from a stock item record - for example taking parts from stock for use. The in-stock quantity for each selected item is decreased by the given amount.
+
+{% with id="stock_remove", url="stock/stock_remove.png", description="Stock removal" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Count Stock
+
+Count stock items (stocktake) to record the number of items in stock at a given point of time. The quantity for each part is pre-filled with the current quantity based on stock item history.
+
+{% with id="stock_count", url="stock/stock_count.png", description="Stock count" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Merge Stock
+
+Users can merge two or more stock items together.
+
+The conditions for merging stock items are the following:
+
+- a stock item cannot be merged with itself
+- only stock items referring to the same part can be merged
+- supplier parts between all items have to match, unless user explicitely allows supplier parts to be different (see below)
+- stock status between all items have to match, unless user explicitely allows stock status to be different (see below).
+
+Moreover, if one of the item:
+
+- is assigned to a sale order
+- or is installed in another item
+- or contains other items
+- or is assigned to a customer
+- or is currenty in production
+- or is serialized
+
+then the merge would not be possible.
+
+If the conditions are met, the process of merging will add up the stock quantity for all items involved in the merge and create a new stock item with the final calculated quantity.
+
+To merge stock items, check two or more items in a stock table and click on the <span class='fas fa-boxes'></span> icon above the table, then click on "<span class='fas fa-object-group'></span> Merge Stock" menu option.
+
+In the Merge Stock Items form, user can decide to allow mismatched suppliers or status to be merged together (disabled by default).
+
+{% with id="stock_item_merge", url="stock/stock_item_merge.png", description="Stock Item Merge" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Select the location for the new stock item and confirm the merge, then click on <span class="badge inventree confirm">Submit</span> to process the merge.

docs/docs/stock/expiry.md

@@ -0,0 +1,77 @@
+---
+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, leave the expiry date field blank, or zero
+
+### 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 and Build Orders
+
+By default, expired Stock Items cannot be added to neither a Sales Order nor a Build Order. This behavior can be adjusted using the *Sell Expired Stock* and *Build Expired Stock* settings:
+
+{% with id="sell_build_expired", url="stock/sell_build_expired_stock.png", description="Sell Build Expired Stock" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/stock/owner.md

@@ -0,0 +1,63 @@
+---
+title: Stock Ownership
+---
+
+## Stock Ownership
+
+InvenTree supports stock ownership, which allows to set groups and users as "owners" of stock locations and items. The owners would be the only users who can edit and manage those stock locations and items.
+
+The stock ownership feature is disabled by default, and must be enabled via the settings menu:
+
+{% with id="stock_owner", url="stock/enable_stock_owner.png", description="Enable stock ownership feature" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! warning "Existing Stock Locations and Items"
+	Enabling the ownership feature will automatically remove the edit permissions to all users for stock locations and items which **do not have** any owner set. Only a user with admin permissions will be able to set the owner for those locations and items.
+
+### Owner: Group vs User
+
+There are two types of owners in InvenTree: [groups](../settings/permissions.md#group) and [users](../settings/permissions.md#user).
+
+* If a group is selected as owner, **all** users linked to the specified group will be able to edit the stock location or item.
+* If a user is selected as owner, only the specified user will be able to edit the stock location or item.
+
+When selecting an owner, in the drop-down list, groups are annotated with the <span class='fas fa-users'></span> icon and users are annotated with the <span class='fas fa-user'></span> icon:
+
+{% with id="stock_owner_type", url="stock/stock_owner_type.png", description="Display stock owner type" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Set Stock Location Owner
+
+To specify the owner of a stock location, navigate to the stock location detail page. Click on the <span class='fas fa-sitemap'></span> icon under the location's name then click on "Edit Location".
+
+!!! warning
+	If you cannot see the <span class='fas fa-sitemap'></span> icon, it means that you do **not** have permissions to edit stock locations. Refer to [the permissions documentation](../../settings/permissions/#roles) and/or contact your InvenTree administrator.
+
+In the "Edit Stock Location" form, select the owner and click the "Submit" button:
+
+{% with id="stock_location_owner", url="stock/stock_location_owner.png", description="Set stock location owner" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Setting the owner of stock location will automatically:
+
+* Set the owner of all children locations to the same owner.
+* Set the owner of all stock items at this location to the same owner.
+
+!!! info
+	If the owner of a children location or a stock item is a subset of the specified owner (eg. a user linked to the specified group), the owner won't be updated.
+
+### Set Stock Item Owner
+
+To specify the owner of a stock item, navigate to the stock item detail page. Click on the <span class='fas fa-tools'></span> icon under the item's name then click on "Edit stock item".
+
+!!! warning
+	If you cannot see the <span class='fas fa-tools'></span> icon, it means that you do **not** have permissions to edit stock items. Refer to [the permissions documentation](../../settings/permissions/#roles) and/or contact your InvenTree administrator.
+
+In the "Edit Stock Item" form, select the owner and click the "Save" button:
+
+{% with id="stock_item_owner", url="stock/stock_item_owner.png", description="Set stock item owner" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/stock/status.md

@@ -0,0 +1,42 @@
+---
+title: Stock Status
+---
+
+## Stock Status
+
+Stock status serves at categorizing and identifying the state of stock items.
+
+Below is the current list of stock status and their proposed meaning:
+
+| Status      | Description |
+| ----------- | ----------- |
+| OK | Stock item is healthy, nothing wrong to report |
+| Attention needed | Stock item hasn't been checked or tested yet |
+| Damaged | Stock item is not functional in its present state |
+| Destroyed | Stock item has been destroyed |
+| Lost | Stock item has been lost |
+| Rejected | Stock item did not pass the quality control standards |
+| Returned | Stock item was returned to seller (if bought) or is a customer return (if sold) |
+| Quarantined | Stock item has been intentionally isolated and it unavailable |
+
+Stock status code will remove the stock from certain operations. For instance, users can't add "destroyed" or "lost" stock to a sales order.
+
+The stock status is displayed as a label in the header of each stock item detail page, for instance here the stock status is "OK":
+
+{% with id="stock_status_label", url="stock/stock_status_label.png", description="Stock Status Label" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## Update Status
+
+In the "Stock" tab of the part view, select all stock items which stock status needs to be updated:
+
+{% with id="stock_status_change_multiple", url="stock/stock_status_change_multiple.png", description="Stock Status Status Multiple" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Click on `Stock Options > Change stock status`, select the new status then submit. All selected stock items status will be automatically updated:
+
+{% with id="stock_status_change_multiple_done", url="stock/stock_status_change_multiple_done.png", description="Stock Status Status Multiple Done" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/stock/stock.md

@@ -0,0 +1,37 @@
+---
+title: Stock
+---
+
+## Stock Location
+
+A stock location represents a physical real-world location where *Stock Items* are stored. Locations are arranged in a cascading manner and each location may contain multiple sub-locations, or stock, or both.
+
+## Stock Item
+
+A *Stock Item* is an actual instance of a [*Part*](../part/part.md) item. It represents a physical quantity of the *Part* in a specific location.
+
+### Stock Item Details
+
+The *Stock Item* detail view shows information regarding the particular stock item:
+
+**Part** - Which *Part* this stock item is an instance of
+
+**Location** - Where is this stock item located?
+
+**Quantity** - How many items are in stock?
+
+**Supplier** - If this part was purcahsed from a *Supplier*, which *Supplier* did it come from?
+
+**Supplier Part** - Link to the particular *Supplier Part*, if appropriate.
+
+**Last Updated** - Date that the stock quantity was last updated
+
+**Last Stocktake** - Date of most recent stocktake (count) of this item
+
+**Status** - Status of this stock item
+
+### Stock Tracking
+
+Every time a *Stock Item* is adjusted, a *Stock Tracking* entry is automatically created. This ensures a complete history of the *Stock Item* is maintained as long as the item is in the system.
+
+Each stock tracking historical item records the user who performed the action.

docs/docs/stock/test.md

@@ -0,0 +1,50 @@
+---
+title: Stock Test Result
+---
+
+## Stock Test Result
+
+Stock items which are associated with a *trackable* part can have associated test data - this is particularly useful for tracking unit testing / commissioning / acceptance data against a serialized stock item.
+
+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.
+
+{% with id="stock_test_results", url="stock/test_results.png", description="Stock Item Test Results" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Test Result Fields
+
+#### Test Name
+
+The name of the test data is used to associate the test with a test template object.
+
+#### Result
+
+Boolean pass/fail status of the test.
+
+#### Value
+
+Optional value uploaded as part of the test data. For example if the test is to record the firmware version of a programmed device, the version number can be added here.
+
+#### Notes
+
+Optional field available for extra notes.
+
+#### Attachment
+
+A given test result may require an attached file which contains extra test information.
+
+### Multiple Test Results
+
+Multiple results can be uploaded against the same test name. In cases where multiple test results are uploaded, the most recent value is used to determine the pass/fail status of the test. It is useful to keep all test records as a given test might be required to run multiple times, if (for example) it fails the first time and then something must be fixed before running the test again.
+
+### Reporting
+
+For any information regarding the reporting architecture, please refer to the [Report Generation](../report/report.md) page.
+
+### Automated Test Intgration
+
+The stock item testing framework is especially useful when integrating with an automated acceptance testing framework. Test results can be uploaded using the [InvenTree API](../api/api.md) or the [InvenTree Python Interface](../api/python/python.md).
+
+!!! info "Example"
+	You design and sell a temperature sensor which needs to be calibrated before it can be sold. An automated calibration tool sets the offset in the device, and uploads a test result to the InvenTree database.

docs/docs/stock/tracking.md

@@ -0,0 +1,140 @@
+---
+title: Stock Tracking
+---
+
+## Stock Tracking
+
+It may be desirable to track individual stock items, or groups of stock items, with unique identifier values. Stock items may be *tracked* using either *Batch Codes* or *Serial Numbers*.
+
+Individual stock items can be assigned a batch code, or a serial number, or both, or neither, as requirements dictate.
+
+{% with id="batch_and_serial", url="stock/batch_and_serial.png", description="Batch and serial number" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Out of the box, the default implementations for both batch codes and serial numbers are (intentionally) simplistic.
+
+As the particular requirements for serial number or batch code conventions may vary significantly from one application to another, InvenTree provides the ability for custom plugins to determine exactly how batch codes and serial numbers are implemented.
+
+### Batch Codes
+
+Batch codes can be used to specify a particular "group" of items, and can be assigned to any stock item without restriction. Batch codes are tracked even as stock items are split into separate items.
+
+Multiple stock items may share the same batch code without restriction, even across different parts.
+
+#### Generating Batch Codes
+
+Batch codes can be generated automatically based on a provided pattern. The default pattern simply uses the current datecode as the batch number, however this can be customized within a certain scope.
+
+{% with id="batch_code_pattern", url="stock/batch_code_template.png", description="Batch code pattern" %}
+{% include 'img.html' %}
+{% endwith %}
+
+#### Plugin Support
+
+To implement custom batch code functionality, refer to the details on the [Validation Plugin Mixin](../extend/plugins/validation.md#batch-codes).
+
+### Serial Numbers
+
+A serial "number" is used to uniquely identify a single, unique stock item. Note that while *number* is used throughout the documentation, these values are not required to be numeric.
+
+#### Uniqueness Requirements
+
+By default, serial numbers must be unique across any given [Part](../part/part.md) instance (including any variants of that part).
+
+However, it is also possible to specify that serial numbers must be globally unique across all types of parts. This is configurable in the settings display (see below):
+
+{% with id="serial_numbers_unique", url="stock/serial_numbers_unique.png", description="Serial number uniqueness" %}
+{% include 'img.html' %}
+{% endwith %}
+
+#### Generating Serial Numbers
+
+When creating a group of serialized stock items, it can be very useful for the user to be able to generate a group of unique serial numbers, with one serial number for each serialized stock item.
+
+{% with id="serial_next", url="stock/serial_next.png", description="Serial number entry" %}
+{% include 'img.html' %}
+{% endwith %}
+
+For a given serial number *schema* (either the in-built schema or a custom schema defined by a plugin), a group (or *range*) of serial numbers can be generated using a number of possible patterns:
+
+##### Comma Separated Values
+
+Individual serial numbers can be specified by separating using a comma character (`,`).
+
+| Pattern | Serial Numbers |
+| --- | --- |
+| `1, 2, 45, 99, 101` | `1, 2, 45, 99, 101` |
+
+##### Hyphen Separated Range
+
+Use a hyphen character (`-`) to specify a *range* of sequential values, inclusive of the two values separated by the hyphen.
+
+| Pattern | Serial Numbers |
+| --- | --- |
+| `10-15` | `10, 11, 12, 13, 14, 15` |
+
+##### Starting Value Range
+
+A *starting value* can be supplied, followed by the plus (`+`) character to indicate a number of sequential values following the provided starting value. The `+` character should be followed by an integer value to indicate the number of serial numbers which will be generated.
+
+| Pattern | Serial Numbers |
+| --- | --- |
+| `10+3` | `10, 11, 12, 13` |
+| `100 + 2` | `100, 101, 102` |
+
+##### Next Value
+
+When specifying serial numbers, the tilde (`~`) character is replaced with the next available serial number. It can be used in combination with the available patterns specified above.
+
+For example, if the *next* available serial number is `100`, the following patterns can be used:
+
+| Pattern | Serial Numbers |
+| --- | --- |
+| `~` | `100` |
+| `~, ~, ~` | `100, 101, 102` |
+| `800, ~, 900` | `800, 100, 900` |
+| `~+5` | `100, 101, 102, 103, 104, 105` |
+
+##### Combination Groups
+
+Any of the above patterns can be combined using multiple groups separated by the comma (`,`) character:
+
+| Pattern | Serial Numbers |
+| --- | --- |
+| `1, 2, 4-7, 10` | `1, 2, 4, 5, 6, 7, 10` |
+| `40+4, 50+4` | `40, 41, 42, 43, 44, 50, 51, 52, 53, 54` |
+| `10, 14, 20+3, 30-35` | `10, 14, 20, 21, 22, 23, 30, 31, 32, 33, 34, 35` |
+
+In the default implementation, InvenTree assumes that serial "numbers" are integer values in a simple incrementing sequence e.g. `{1, 2, 3, 4, 5, 6}`. When generating the *next* value for a serial number, the algorithm looks for the *most recent* serial number, and attempts to coerce that value into an integer, and then increment that value.
+
+While this approach is reasonably robust, it is definitely simplistic and is not expected to meet the requirements of every installation. For this reason, more complex serial number management is intented to be implemented using a custom plugin (see below).
+
+#### Serial Number Errors
+
+If a provided serial number (or group of numbers) is not considered valid, an error message is provided to the user.
+
+##### Example: Invalid Quantity
+
+{% with id="serial_error_quantity", url="stock/serial_error_quantity.png", description="Serial number - invalid quantity" %}
+{% include 'img.html' %}
+{% endwith %}
+
+##### Example: Duplicate Serial Numbers
+
+{% with id="serial_error_unique", url="stock/serial_error_unique.png", description="Serial number - duplicate values" %}
+{% include 'img.html' %}
+{% endwith %}
+
+##### Example: Invalid Serial Numbers
+
+!!! tip "Serial Number Validation"
+    Custom serial number validation can be implemented using an external plugin
+
+#### Plugin Support
+
+Custom serial number functionality, with any arbitrary requirements or level of complexity, can be implemented using the [Validation Plugin Mixin class](../extend/plugins/validation.md#serial-numbers). Refer to the documentation for this plugin for technical details.
+
+A custom plugin allows the user to determine how a "valid" serial number is defined, and (crucially) how any given serial number value is incremented to provide the next value in the sequence.
+
+Implementing custom methods for these two consideraions allows for complex serial number schema to be supported with minimal effort.