API docs (#379)

* Move API documentation into separate directory

* Rearrange main docs bar

* Split python examples into separate page

* Fix broken links

* Adds page for browseable API

* Fix image links

* Add entrypoint page for barcodes

* Update barcode docs

* Add (empty) pages for internal and external barcods

* Add documentation on "internal" barcode format

* Documentation for external barcode functionality

* Skeleton page for custom barcode information

* Extend docs for custom barcodesplugins

* Add stubs for new API docs

* Add documentation for downloading data via the AP

* API metadata information

* docs for pythonic metadata access

* docs for bulk delete

docs/api/api.md

@@ -4,7 +4,10 @@ title: InvenTree API
 
 ## InvenTree API
 
-InvenTree provides a powerful REST API for interacting with inventory data on the server. Low-level data access and manipulation is available, with integrated user authentication and data validation
+InvenTree provides a powerful REST API for interacting with inventory data on the server. Low-level data access and manipulation is available, with integrated user authentication and data validation.
+
+!!! info "Django REST Framework"
+    The InvenTree API is based on the powerful and flexible [Django REST Framework](https://www.django-rest-framework.org/).
 
 ## Documentation
 
@@ -21,6 +24,10 @@ Users must be authenticated to gain access to the InvenTree API. The API accepts
 !!! warning "Permissions"
     API access is restricted based on the permissions assigned to the user.
 
+### Basic Auth
+
+Users can authenticate against the API using basic authentication - specifically a valid combination of `username` and `password` credentials.
+
 ### Tokens
 
 Each user is assigned an authentication token which can be used to access the API. This token is persistent for that user (unless invalidated by an administrator) and can be used across multiple sessions.
@@ -52,7 +59,7 @@ HTTP_200_OK
 
 After reception of a valid authentication token, it can be subsequently used to perform token-based authentication.
 
-The token value sent to the server must be of the format `Token <TOKEN-VALUE>` (without the < and > characters).
+The token value sent to the server must be of the format `Token <TOKEN-VALUE>` (without the `<` and `>` characters).
 
 **Example: Javascript**
 ```javascript

docs/api/browse.md

@@ -0,0 +1,37 @@
+---
+title: Interactive API
+---
+
+## Interactive API
+
+If the server is running in [Debug Mode](../start/intro.md#debug-mode) then an interactive version of the API is available using a browser.
+
+!!! info "Debug Mode"
+    This interactive API is only available when running the server in debug mode
+
+!!! warning "Slow Traffic Ahead"
+    The interactive API is *significantly* slower than using the normal JSON format. It is provided only for development and testing.
+
+### List View
+
+Various list endpoints can be displayed as shown below:
+
+{% with id="api_browse", url="api/api_browse.png", description="List API" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Filtering
+
+List views can be filtered interactively:
+
+{% with id="api_filter", url="api/api_filters.png", description="Filter API" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Detail View
+
+Detail view endpoints can also be displayed:
+
+{% with id="api_detail", url="api/api_detail.png", description="Detail API" %}
+{% include 'img.html' %}
+{% endwith %}

docs/api/bulk_delete.md

@@ -0,0 +1,44 @@
+---
+title: Bulk Deletion
+---
+
+## Bulk Deletion
+
+While deleting items individually via the API is supported, it can prove inefficient (time consuming) when multiple items are to be deleted sequentially.
+
+For example, if the user wishes to delete a large number items (such as lines from a [Bill of Materials](../build/bom.md)), these items are deleted sequentially, with each `DELETE` separate request requiring network transfer, database access, cleanup, etc.
+
+A much more efficient approach is to allow for "bulk deletion" of multiple database items in a single transaction. This means that only one network request is required, and only a single database access request.
+
+So, InvenTree supports a custom "bulk deletion" endpoint which is available for some database models.
+
+## Item Filtering
+
+In a "regular" `DELETE` action, the pk (primary key) of the target object is provided, to designate which object is going to be removed from the database:
+
+`DELETE /api/part/10/`
+
+However this approach does not work if we wish to delete multiple items. To determine which items are to be deleted, additional data can be added to the query (as you would do with a normal `POST` request, for example).
+
+### Primary Key Values
+
+The request can specify a list of individual pk (primary key) values to delete, using the `items` variable:
+
+```json
+{
+    "items": [1, 10, 50, 99]
+}
+```
+
+### Filters
+
+The request can also specify a list of filters to be applied to the database query. Any items which match the filters will be deleted. Here, use the `filters` variable:
+
+```
+{
+    "filters": {
+        "active": False,
+        "category": 7.
+    }
+}
+```

docs/api/download.md

@@ -0,0 +1,23 @@
+---
+title: Data Download
+---
+
+## Data Download
+
+Some API endpoints provide a *download* function, whereby the data presented at the API endpoint can be downloaded as a tabulated file.
+
+To export API data to a file, add the `&export=<format>` modifier to the query. The following file formats are supported:
+
+| File Format | Modifier |
+| --- | --- | 
+| csv | `&format=csv` |
+| tsv | `&format=tsv` |
+| xls | `&format=xls` |
+| xlsx | `&format=xlsx` |
+
+### Query Filters
+
+Any other query filters used in the API request are also observed when downloading the data. For example, to download a list of all stock items in a given location:
+
+`<host>/api/stock/?format=csv&location=10`
+

docs/api/metadata.md

@@ -0,0 +1,92 @@
+---
+title: Model Metadata
+---
+
+## Model Metadata
+
+The API is *self describing* in that it provides metadata about the various fields available at any given endpoint. External applications (such as the [python interface](../api/python/python.md)) can introspect the API to determine information about the model fields.
+
+!!! tip "API Forms"
+    The various forms implemented in the InvenTree web interface make heavy use of this metadata feature    
+
+### Requesting Metadata
+
+To request metadata about a particular API endpoint, simply perform an `OPTIONS` method request against the API URL.
+
+For example, to view the metadata available for creating a new [Part Category](../part/part.md#part-category), an `OPTIONS` request to `/api/part/category/` yields:
+
+{% with id="api_cat_options", url="api/api_category_options.png", description="Part category options" %}
+{% include 'img.html' %}
+{% endwith %}
+
+You can see here a detailed list of the various fields which are available for this API endpoint.
+
+## Metadata Information
+
+The `OPTIONS` endpoint provides the following information:
+
+| Entry | Description |
+| --- | --- |
+| name | The human-readable name of the API endpoint |
+| description | Descriptive detail for the endpoint, extracted from the python docstring |
+| actions | Contains the available HTTP actions and field information (see below) |
+
+Specific details are provided on the available attributes of each field:
+
+{% with id="api_fields", url="api/api_metadata_fields.png", description="Metadata fields" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Field Types
+
+Supported field types are:
+
+| Field Type | Description |
+| --- | --- |
+| string | Text data |
+| boolean | true / false value |
+| integer | Integer numbers |
+| float | Floating point numbers |
+| related field | Primary key value for a foreign-key relationship in the database |
+
+### Field Attributes
+
+Each named field provides information on available attributes:
+
+| Attribute | Description |
+| --- | --- |
+| type | Defines the [field type](#field-types) |
+| default | The default value for this field. Will be assumed if no value is supplied |
+| required | Boolean value, whether this field must be supplied |
+| read_only | Boolean value, whether this field is writeable |
+| label | Human readable descriptive label for this field. |
+| help_text | Long form descriptor for this field. |
+| min_value | Minimum allowed value (for numeric fields) |
+| max_value | Maximum allowed value (for numeric fields) |
+| max_length | Maximum allowed length (for text fields) |
+| model | Name of the database model, if this field represents a foreign-key relationship |
+| api_url | API url for the related model, if this field represents a foreign-key relationship |
+| filters | API filters for the field, if this field represents a foreign-key relationship |
+
+!!! tip "Field Name"
+    The field name is the *key* used to define the field itself
+
+!!! info "Available Attributes"
+    Some attributes may not be made available for a particular field
+
+
+
+## Translation
+
+Field *label* and *help text* values are localized using the [community contributed translations](../contribute.md#translation). The required locale information is determined from the API request itself, meaning that the translated values are provided automatically.
+
+For example, the same forms (in the web interface) are served via identical API requests, with the locale information determined "on the fly":
+
+{% with id="api_english", url="api/api_english.png", description="API forms (english)" %}
+{% include 'img.html' %}
+{% endwith %}
+
+{% with id="api_german", url="api/api_german.png", description="API forms (german)" %}
+{% include 'img.html' %}
+{% endwith %}
+

docs/api/python/examples.md

@@ -1,122 +1,12 @@
 ---
-title: Python Interface
+title: Python Interface Examples
 ---
 
-## Python Module
-
-A [Python module](https://github.com/inventree/inventree-python) is provided for rapid development of third party scripts or applications using the REST API. The python module handles authentication and API transactions, providing an extremely clean interface for interacting with and manipulating database data.
-
-### Features
-
-- Automatic authentication management using token-based authentication
-- Pythonic data access
-- Native file uploads
-- Powerful functions for accessing related model data
-
-### Installation
-
-The inventree python interface can be easily installed via the [PIP package manager](https://pypi.org/project/inventree/):
-
-```
-pip3 install inventree
-```
-
-!!! tip "Upgrading"
-    To upgrade to the latest version, run `pip install --upgrade inventree`
-
-Alternatively, it can downloaded and installed from source, from [GitHub](https://github.com/inventree/inventree-python).
-
-### Authentication
-
-Authentication against an InvenTree server is simple:
-
-#### Basic Auth
-
-Connect using your username/password as follows:
-
-```python
-from inventree.api import InvenTreeAPI
-
-SERVER_ADDRESS = 'http://127.0.0.1:8000'
-MY_USERNAME = 'not_my_real_username'
-MY_PASSWORD = 'not_my_real_password'
-
-api = InvenTreeAPI(SERVER_ADDRESS, username=MY_USERNAME, password=MY_PASSWORD)
-```
-
-#### Token Auth
-
-Alternatively, if you already have an access token:
-
-```python
-api = InvenTreeAPI(SERVER_ADDRESS, token=MY_TOKEN)
-```
-
-#### Environment Variables
-
-Authentication variables can also be set using environment variables:
-
-- `INVENTREE_API_HOST`
-- `INVENTREE_API_USERNAME`
-- `INVENTREE_API_PASSWORD`
-- `INVENTREE_API_TOKEN`
-
-And simply connect as follows:
-
-```python
-api = InvenTreeAPI()
-```
-
-
-### Retrieving Data
-
-Once a connection is established to the InvenTree server, querying individual items is simple.
-
-#### Single Item
-
-If the primary-key of an object is already known, retrieving it from the database is performed as follows:
-
-```python
-from inventree.part import PartCategory
-
-category = PartCatgory(api, 10)
-```
-
-#### Multiple Items
-
-Database items can be queried by using the `list` method for the given class. Note that arbitrary filter parameters can be applied (as specified by the [InvenTree API](./api.md)) to filter the returned results.
-
-```python
-from inventree.part import Part
-from inventree.stock import StockItem
-
-parts = Part.list(api, category=10, assembly=True)
-items = StockItem.list(api, location=4, part=24)
-```
-
-The `items` variable above provides a list of `StockItem` objects.
-
-### Item Methods
-
-Once an object has been retrieved from the database, its related objects can be returned with the provided helper methods:
-
-```python
-part = Part(api, 25)
-stock_items = part.getStockItems()
-```
-
-Some classes also have helper functions for performing certain actions, such as uploading file attachments or test results:
-
-```python
-stock_item = StockItem(api, 1001)
-stock_item.uploadTestResult("Firmware", True, value="0x12345678", attachment="device_firmware.bin")
-```
-
-### Examples
+## Examples
 
 Following is a *non-exhaustive* list of examples of the capabilities provided by the python library. For a complete look at what it can do, [read the source code](https://github.com/inventree/inventree-python)!
 
-#### Creating New Items
+### Creating New Items
 
 Use the `create` method to add new items to the database:
 
@@ -144,7 +34,7 @@ couch = Part.create(api, {
 })
 ```
 
-#### Updating Attributes
+### Updating Attributes
 
 Most model fields which are exposed via the API can be directly edited using the python interface, by simply calling the `save()` method as shown below:
 
@@ -175,9 +65,9 @@ print("Minimum stock:", part.minimum_stock)
 !!! info "Read Only Fields"
     Note that some fields are read-only and cannot be edited via the API
 
-#### Adding Parameters
+### Adding Parameters
 
-Each [part](../part/part.md) can have multiple [parameters](../part/parameter.md). For the example of the sofa (above) *length* and *weight* make sense. Each parameter has a parameter template that combines the parameter name with a unit. So we first have to create the parameter templates and afterwards add the parameter values to the sofa.
+Each [part](../../part/part.md) can have multiple [parameters](../../part/parameter.md). For the example of the sofa (above) *length* and *weight* make sense. Each parameter has a parameter template that combines the parameter name with a unit. So we first have to create the parameter templates and afterwards add the parameter values to the sofa.
 
 ```python
 from inventree.part import Parameter
@@ -195,7 +85,7 @@ These parameter templates need to be defined only once and can be used for all o
 couch.upload_image('my_nice_couch.jpg')
 ```
 
-#### Adding Location Data
+### Adding Location Data
 
 If we have several sofas on stock we need to know there we have stored them. So let’s add stock locations to the part. Stock locations can be organized in a hierarchical manner e.g. boxes in shelves in aisles in rooms. So each location can have a parent. Let’s assume we have 10 sofas in box 12 and 3 sofas in box 13 located in shelve 43 aisle 3. First we have to create the locations, afterwards we can put the sofas inside.
 
@@ -227,7 +117,7 @@ Please recognize the different status flags. 10 means OK, 55 means damaged. We h
 * 70: Lost
 * 85: Returned
 
-#### Adding Manufacturers and Supplier
+### Adding Manufacturers and Supplier
 
 We can add manufacturers and suppliers to parts. We first need to create two companies, ACME (manufacturer) and X-Store (supplier).
 
@@ -274,7 +164,7 @@ SupplierPart.create(api,{
 })
 ```
 
-#### Stock Adjustments
+### Stock Adjustments
 
 Various stock adjustment actions can be performed as follows:
 
@@ -298,7 +188,7 @@ loc = StockLocation(api, pk=12)
 item.transferStock(loc, quantity=50)
 ```
 
-#### Bulk Delete
+### Bulk Delete
 
 Some database models support bulk delete operations, where multiple database entries can be deleted in a single API query.
 
@@ -309,7 +199,7 @@ from inventree.stock import StockItem
 StockItem.bulkDelete(api, filters={'category': 3})
 ```
 
-#### Upload Attachments
+### Upload Attachments
 
 We have the possibility to upload attachments against a particular Part. We can use pdf for documents but also other files like 3D drawings or pictures. To do so we add the following commands:
 
@@ -331,8 +221,4 @@ from inventree.part import Part
 part = Part(api, pk=47)
 
 part.uploadAttachment('data.txt', comment='A data file')
-```
-
-### Further Reading
-
-The [InvenTree Python Interface](https://github.com/inventree/inventree-python) is open source, and well documented. The best way to learn is to read through the source code and try for yourself!
+```

docs/api/python/python.md

@@ -0,0 +1,149 @@
+---
+title: Python Interface
+---
+
+## Python Module
+
+A [Python module](https://github.com/inventree/inventree-python) is provided for rapid development of third party scripts or applications using the REST API. The python module handles authentication and API transactions, providing an extremely clean interface for interacting with and manipulating database data.
+
+### Features
+
+- Automatic authentication management using token-based authentication
+- Pythonic data access
+- Native file uploads
+- Powerful functions for accessing related model data
+
+### Installation
+
+The inventree python interface can be easily installed via the [PIP package manager](https://pypi.org/project/inventree/):
+
+```
+pip3 install inventree
+```
+
+!!! tip "Upgrading"
+    To upgrade to the latest version, run `pip install --upgrade inventree`
+
+Alternatively, it can downloaded and installed from source, from [GitHub](https://github.com/inventree/inventree-python).
+
+### Authentication
+
+Authentication against an InvenTree server is simple:
+
+#### Basic Auth
+
+Connect using your username/password as follows:
+
+```python
+from inventree.api import InvenTreeAPI
+
+SERVER_ADDRESS = 'http://127.0.0.1:8000'
+MY_USERNAME = 'not_my_real_username'
+MY_PASSWORD = 'not_my_real_password'
+
+api = InvenTreeAPI(SERVER_ADDRESS, username=MY_USERNAME, password=MY_PASSWORD)
+```
+
+#### Token Auth
+
+Alternatively, if you already have an access token:
+
+```python
+api = InvenTreeAPI(SERVER_ADDRESS, token=MY_TOKEN)
+```
+
+#### Environment Variables
+
+Authentication variables can also be set using environment variables:
+
+- `INVENTREE_API_HOST`
+- `INVENTREE_API_USERNAME`
+- `INVENTREE_API_PASSWORD`
+- `INVENTREE_API_TOKEN`
+
+And simply connect as follows:
+
+```python
+api = InvenTreeAPI()
+```
+
+### Retrieving Data
+
+Once a connection is established to the InvenTree server, querying individual items is simple.
+
+#### Single Item
+
+If the primary-key of an object is already known, retrieving it from the database is performed as follows:
+
+```python
+from inventree.part import PartCategory
+
+category = PartCatgory(api, 10)
+```
+
+#### Multiple Items
+
+Database items can be queried by using the `list` method for the given class. Note that arbitrary filter parameters can be applied (as specified by the [InvenTree API](../api.md)) to filter the returned results.
+
+```python
+from inventree.part import Part
+from inventree.stock import StockItem
+
+parts = Part.list(api, category=10, assembly=True)
+items = StockItem.list(api, location=4, part=24)
+```
+
+The `items` variable above provides a list of `StockItem` objects.
+
+### Item Attributes
+
+The available model attributes are determined by introspecting [API metadata](../metadata.md). To view the fields (attributes) availabel for a given database model type within the python interface, use the `fieldNames` and `fieldInfo` methods, as below:
+
+```python
+from inventree.api import InvenTreeAPI
+from inventree.part import Part
+
+api = InvenTreeAPI("http://localhost:8000", username="admin", password="inventree")
+
+fields = Part.fieldNames(api)
+
+for field in Part.fieldNames(api):
+    print(field, '->', Part.fieldInfo(field, api))
+```
+
+```
+active -> {'type': 'boolean', 'required': True, 'read_only': False, 'label': 'Active', 'help_text': 'Is this part active?', 'default': True, 'max_length': None}
+allocated_to_build_orders -> {'type': 'float', 'required': True, 'read_only': True, 'label': 'Allocated to build orders'}
+allocated_to_sales_orders -> {'type': 'float', 'required': True, 'read_only': True, 'label': 'Allocated to sales orders'}
+assembly -> {'type': 'boolean', 'required': True, 'read_only': False, 'label': 'Assembly', 'help_text': 'Can this part be built from other parts?', 'default': False, 'max_length': None}
+category -> {'type': 'related field', 'required': True, 'read_only': False, 'label': 'Category', 'model': 'partcategory', 'api_url': '/api/part/category/', 'filters': {}, 'help_text': 'Part category', 'max_length': None}
+component -> {'type': 'boolean', 'required': True, 'read_only': False, 'label': 'Component', 'help_text': 'Can this part be used to build other parts?', 'default': True, 'max_length': None}
+default_expiry -> {'type': 'integer', 'required': True, 'read_only': False, 'label': 'Default Expiry', 'help_text': 'Expiry time (in days) for stock items of this part', 'min_value': 0, 'max_value': 2147483647, 'default': 0, 'max_length': None}
+...
+variant_stock -> {'type': 'float', 'required': True, 'read_only': True, 'label': 'Variant stock'}
+```
+
+
+### Item Methods
+
+Once an object has been retrieved from the database, its related objects can be returned with the provided helper methods:
+
+```python
+part = Part(api, 25)
+stock_items = part.getStockItems()
+```
+
+Some classes also have helper functions for performing certain actions, such as uploading file attachments or test results:
+
+```python
+stock_item = StockItem(api, 1001)
+stock_item.uploadTestResult("Firmware", True, value="0x12345678", attachment="device_firmware.bin")
+```
+
+#### Discovering Methods
+
+You can determine the available methods by either [reading the source code](https://github.com/inventree/inventree-python) or using the `dir()` function in an interactive terminal.
+
+### Further Reading
+
+The [InvenTree Python Interface](https://github.com/inventree/inventree-python) is open source, and well documented. The best way to learn is to read through the source code and try for yourself!

docs/app/app.md

@@ -8,7 +8,7 @@ title: InvenTree Mobile App
 
 -----
 
-The InvenTree Mobile App brings stock control to your pocket. Integrating seamlessly with the [InvenTree API](../extend/api.md), the app provides immediate access to inventory data without requiring physical access to a computer.
+The InvenTree Mobile App brings stock control to your pocket. Integrating seamlessly with the [InvenTree API](../api/api.md), the app provides immediate access to inventory data without requiring physical access to a computer.
 
 Native barcode support provides a multitude of context-sensitive stock control actions, allowing streamlined inventory management at your fingertips. The app has been optimized for speed, providing instant access to stock knowledge and handy on-site functionality.
 

docs/barcodes/barcodes.md

@@ -0,0 +1,58 @@
+---
+title: Barcodes
+---
+
+## Barcode Support
+
+InvenTree has native support for barcodes, which provides powerful functionality "out of the box", and can be easily extended:
+
+- Barcodes can be scanned [via the API](../api/api.md)
+- The web interface supports barcode scanning
+- Barcodes integrate natively [with the mobile app](../app/barcode.md)
+- Custom barcodes can be assigned to items
+- Barcodes can be embedded in [labels or reports](../report/barcodes.md)
+- Barcode functionality can be [extended via plugins](../extend/plugins/barcode.md)
+
+### Barcode Data Types
+
+Barcodes can be linked with the following data model types:
+
+- [Part](../part/part.md#part)
+- [Stock Item](../stock/stock.md#stock-item)
+- [Stock Location](../stock/stock.md#stock-location)
+- [Supplier Part](../buy/supplier.md#supplier-parts)
+
+## Web Integration
+
+Barcode scanning can be enabled within the web interface. Barcode scanning in the web interface supports scanning via:
+
+- Keyboard style scanners (e.g. USB connected)
+- Webcam (image processing)
+
+### Configuration
+
+Barcode scanning may need to be enabled for the web interface:
+
+{% with id="barcode_config", url="barcode/barcode_settings.png", description="Barcode settings" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Scanning
+
+When enabled, select the barcode icon in the top-right of the menu bar to scan a barcode. If the barcode is recognized by the system, the web browser will automatically navigate to the correct item:
+
+{% with id="barcode_scan", url="barcode/barcode_scan.png", description="Barcode scan" %}
+{% include 'img.html' %}
+{% endwith %}
+
+#### No Match Found
+
+If no match is found for the scanned barcode, the following error message is displayed:
+
+{% with id="barcode_no_match", url="barcode/barcode_no_match.png", description="No match for barcode" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## App Integration
+
+Barcode scanning is a key feature of the [companion mobile app](../app/barcode.md).

docs/barcodes/custom.md

@@ -0,0 +1,28 @@
+---
+title: Custom Barcodes
+---
+
+## Custom Barcode Functionality
+
+With the provision of [internal](./internal.md) and [external](./external.md) barcode support, a lot of potential use-cases are already supported directly by InvenTree.
+
+However, if further customization is required, or a bespoke barcode workflow which is not supported already, then this can easily be implemented using the [plugin system](../extend/plugins/barcode.md).
+
+A custom barcode plugin can be used to (for example) perform a particular action when a barcode is scanned.
+
+### Scanning a Barcode
+
+To scan (process) a barcode, the barcode data is sent via a `POST` request to the `/api/barcode/` API endpoint.
+
+### Barcode Scanning Priority
+
+When a barcode is scanned (sent to the `/barcode/scan/` endpoint), each available "plugin" is checked to see if it returns a valid result for the provided barcode data. The first plugin to return a result prevents any further plugins from being checked.
+
+The barcode is tested as follows, in decreasing order of priority:
+
+- [Internal Barcode Plugin](./internal.md)
+- [External Barcode Plugin](./external.md)
+- [Custom Barcode Plugins](../extend/plugins/barcode.md)
+
+!!! tip "Plugin Loading Order"
+    The first custom plugin to return a result "wins". As the loading order of custom plugins is not defined (or configurable), take special care if you are running multiple plugins which support barcode actions.

docs/barcodes/external.md

@@ -0,0 +1,45 @@
+---
+title: External Barcodes
+---
+
+## External Barcodes
+
+In addition to defining an [internal barcode format](./internal.md), models which have associated barcode information also allow arbitrary external (third party) barcodes to be assigned or "linked" to items in the database.
+
+For example, you have just purchased a reel of capacitors from a supplier, which comes provided with a sufficiently unique barcode or qr-code. Instead of printing an *internal* barcode, the existing barcode can be scanned and *linked* to the specific reel (which is a [Stock Item](../stock/stock.md#stock-item)).
+
+Linking to external barcodes allows an alternative barcode workflow, which may be especially useful when dealing with in-feed components which are received from external suppliers.
+
+!!! tip "Dealer's Choice"
+    The use of external barcodes is entirely up to the user, if it is deemed to be convenient.
+
+## Linking Barcodes
+
+### Via the API
+
+Facility for barcode linking (and un-linking) is provided via the [API](../api/api.md).
+
+- The `/api/barcode/link/` API endpoint is used to link a barcode with an existing database item
+- The `/api/barcode/unlink/` API endpoint is used to unlink a barcode from an existing database item
+
+### Via the Web Interface
+
+To link an arbitrary barcode, select the *Link Barcode* action as shown below:
+
+{% with id="barcode_link_1", url="barcode/barcode_link_1.png", description="Link barcode" %}
+{% include 'img.html' %}
+{% endwith %}
+
+{% with id="barcode_link_2", url="barcode/barcode_link_2.png", description="Link barcode" %}
+{% include 'img.html' %}
+{% endwith %}
+
+If an item already has a linked barcode, it can be un-linked by selecting the *Unlink Barcode* action:
+
+{% with id="barcode_unlink", url="barcode/barcode_unlink.png", description="Unlink barcode" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Via the App
+
+External barcodes can be linked to (or unlinked from) database items via the [mobile app](../app/barcode.md)

docs/barcodes/internal.md

@@ -0,0 +1,36 @@
+---
+title: Internal Barcodes
+---
+
+## Internal Barcodes
+
+InvenTree defines an internal format for generating barcodes for various items. This format uses a simple JSON-style string to uniquely identify an item in the database.
+
+Some simple examples of this format are shown below:
+
+| Model Type | Example Barcode |
+| --- | --- |
+| Part | `{% raw %}{"part": 10}{% endraw %}` |
+| Stock Item | `{% raw %}{"stockitem": 123}{% endraw %}` |
+| Supplier Part | `{% raw %}{"supplierpart": 99}{% endraw %}` |
+
+The numerical ID value used is the *Primary Key* (PK) of the particular object in the database.
+
+## Report Integration
+
+This barcode format can be used to generate 1D or 2D barcodes (e.g. for [labels and reports](../report/barcodes.md))
+
+To access the raw barcode information string within a template, use the `.barcode` attribute, and pass it into a barcode generation method.
+
+### Example: QR Code
+
+For example, to render a QR-Code image for a part instance:
+
+```html
+{% raw %}
+<img src='{% qrcode part.barcode %}'>
+{% endraw %}
+```
+
+!!! info "Barcode Formatting"
+    Refer to the [report documentation](../report/barcodes.md) for further information on formatting barcode data

docs/features.md

@@ -48,8 +48,15 @@ Builds consume stock items to make new parts, you can decide to automatically or
 
 Generate a wide range of reports using custom templates. [Read more...](./report/report.md)
 
+## API
+
+The core InvenTree software is implemented on top of a RESTful API, which can be used by external applications. Additionally, a native Python binding library is provided, for rapid development of programs to integrate with InvenTree.
+
+[Read more...](./api/api.md)
+
 ## Extend and Customize
 
-InvenTree is designed to be highly extensible. If the core InvenTree functionality does not meet your particular need, InvenTree provides a RESTful API, a native Python library, and a powerful plugin system.
+InvenTree is designed to be highly extensible. If the core InvenTree functionality does not meet your particular need, InvenTree provides a powerful plugin system which can be used to extend on base functions as required.
+
+[Read more...](./extend/plugins.md)
 
-[Read more...](./extend/api.md)

docs/part/create.md

@@ -64,6 +64,6 @@ If the *Add Supplier Data* option is checked, then supplier part and manufacture
 
 The following alternative methods for creating parts are supported:
 
-- [Via the REST API](../../extend/api)
-- [Using the Python library](../../extend/python)
+- [Via the REST API](../../api/api)
+- [Using the Python library](../../api/python)
 - [Within the Admin interface](../../settings/admin)

docs/releases/0.1.7.md

@@ -31,7 +31,7 @@ Label printing functionality has been simplified and brought into line with the
 
 ### API Permissions
 
-[#1363](https://github.com/inventree/InvenTree/pull/1363) enforces user role permissions onto the REST API endpoints. Authenticated users can now only perform REST actions which align with their allocated role(s). Refer to the [API documentation](../extend/api.md#authorization) for further information.
+[#1363](https://github.com/inventree/InvenTree/pull/1363) enforces user role permissions onto the REST API endpoints. Authenticated users can now only perform REST actions which align with their allocated role(s). Refer to the [API documentation](../api/api.md#authorization) for further information.
 
 ### Query Pagination
 

docs/stock/test.md

@@ -44,7 +44,7 @@ For any information regarding the reporting architecture, please refer to the [R
 
 ### 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](../extend/api.md) or the [InvenTree Python Interface](../extend/python.md).
+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.

mkdocs.yml

@@ -133,6 +133,31 @@ nav:
     - Email: settings/email.md
     - Background Tasks: settings/tasks.md
   - Extend:
+    - InvenTree API:
+      - Overview: api/api.md
+      - Model Metadata: api/metadata.md
+      - Download Data: api/download.md
+      - Bulk Delete: api/bulk_delete.md
+      - Interactive API: api/browse.md
+    - Python Interface: 
+      - Overview: api/python/python.md
+      - Examples: api/python/examples.md
+    - Barcodes:
+      - Overview: barcodes/barcodes.md
+      - Internal Barcodes: barcodes/internal.md
+      - External Barcodes: barcodes/external.md
+      - Custom Barcodes: barcodes/custom.md
+    - App:
+      - InvenTree App: app/app.md
+      - Connect: app/connect.md
+      - Barcodes: app/barcode.md
+      - Parts: app/part.md
+      - Stock: app/stock.md
+      - Purchase Orders: app/po.md
+      - Settings: app/settings.md
+      - Privacy: app/privacy.md
+      - Translation: app/translation.md
+      - Suggestions: app/issues.md
     - Plugins:
       - Overview: extend/plugins.md
       - Installation: extend/plugins/install.md
@@ -151,21 +176,8 @@ nav:
       - Settings Mixin: extend/plugins/settings.md
       - URL Mixin: extend/plugins/urls.md
       - Validation Mixin: extend/plugins/validation.md
-    - API: extend/api.md
-    - Python Interface: extend/python.md
     - Themes: extend/themes.md
     - Third-Party: extend/integrate.md
-  - App:
-    - InvenTree App: app/app.md
-    - Connect: app/connect.md
-    - Barcodes: app/barcode.md
-    - Parts: app/part.md
-    - Stock: app/stock.md
-    - Purchase Orders: app/po.md
-    - Settings: app/settings.md
-    - Privacy: app/privacy.md
-    - Translation: app/translation.md
-    - Suggestions: app/issues.md
 
 # Plugins
 plugins: