Merge remote-tracking branch 'inventree/master'

README.md

@@ -38,6 +38,24 @@ Once the server is running, it will monitor the documentation files for any chan
 
 Refer to the [reference documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) to customize the admonition block to the use-case (eg. warning, missing, info, etc.).
 
+### Internal Links
+
+Links to internal documentation pages **must** use relative pathing, otherwise the link will be broken by the readthedocs URL formatting.
+
+For example, to link to the page `/part/views` from `/stock/stocktake`, the link must be formed as follows:
+
+```
+Click [here](../../part/views)
+```
+
+*Formatting the link as follows:*
+
+```
+Click [here](/part/views)
+```
+
+*will result in a broken link.*
+
 ### Images
 
 Images are served from the `./docs/assets/images` folder and can be added as follow:

docs/admin/admin.md

@@ -9,7 +9,7 @@ Users which have *staff* privileges have access to an Admin interface which prov
 !!! warning "Caution"
 	Admin users should exercise extreme care when modifying data via the admin interface, as performing the wrong action may have unintended consequences!
 
-The admin interface allows *staff* users the ability to directly view / add / edit / delete database entries according to their [user permissions](/admin/permissions).
+The admin interface allows *staff* users the ability to directly view / add / edit / delete database entries according to their [user permissions](../permissions).
 
 ### Access Admin Interface
 

docs/admin/export.md

@@ -4,7 +4,7 @@ title: Exporting Data
 
 ## Exporting Data
 
-The [Admin Interface](/admin/admin) provides powerful data exporting capability. When displaying a list of items which support exporting (e.g. Part objects), select the "Export" button from the top-right corner:
+The [Admin Interface](../admin) provides powerful data exporting capability. When displaying a list of items which support exporting (e.g. Part objects), select the "Export" button from the top-right corner:
 
 {% with id="export", url="admin/export.png", description="Data export" %}
 {% include 'img.html' %}

docs/build/bom.md

@@ -4,7 +4,7 @@ title: Bill of Materials
 
 ## Bill of Materials
 
-A Bill of Materials (BOM) defines the list of component parts required to make an assembly, [create builds](/build/build) and allocate inventory.
+A Bill of Materials (BOM) defines the list of component parts required to make an assembly, [create builds](../build) and allocate inventory.
 
 ### Add BOM Item
 

docs/build/build.md

@@ -36,7 +36,7 @@ A "basic" build flow is as follow:
 
 A Part BOM is required to allocate inventory to a build.
 
-Read through the [Bill of Materials documentation](/build/bom).
+Read through the [Bill of Materials documentation](../bom).
 
 ### Build Order
 

docs/contribute.md

@@ -31,8 +31,13 @@ Documenting a large software project is a challenging and ongoing effort. If you
 
 ### Donate
 
+{% if 'readthedocs.org' in config.docs_dir %}
+{% set assets = '/en/latest/assets' %}
+{% else %}
+{% set assets = '/assets' %}
+{% endif %}
+
 If you are unable to provide contributions as listed above, or you find InvenTree to be useful, please consider donating to support its ongoing development.
 
-[ Donate :material-emoticon-cool: ](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=T4M976M5URSUE&currency_code=AUD){: .md-button .md-button--primary }
+[ Donate <!-- :material-emoticon-cool: --> ](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=T4M976M5URSUE&currency_code=AUD){: .md-button .md-button--primary }
-<img src="/assets/paypal-logo-small-min-300x136.png" border="0" alt="PayPal Logo" style="width: 102px; length:225px; vertical-align:middle;">
+<img src="{{ assets }}/paypal-logo-small-min-300x136.png" border="0" alt="PayPal Logo" style="width: 136px; length:300px; vertical-align:middle; padding-left: 20px">
-

docs/extend/api.md

@@ -6,7 +6,7 @@ title: 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
 
-### Documentation
+## Documentation
 
 The API is self-documenting, and the documentation is provided alongside any InvenTree installation instance. If (for example) you have an InvenTree instance running at `http://127.0.0.1:8000` then the API documentation is available at `http://127.0.0.1:8000/api-doc/`
 
@@ -14,13 +14,31 @@ The API is self-documenting, and the documentation is provided alongside any Inv
 {% include 'img.html' %}
 {% endwith %}
 
-### Authentication
+## Authentication
 
-The API uses token-based authentication for fast data access. To obtain a valid token, perform a GET request to `/api/user/token/` (no data are required).
+Users must be authenticated to gain access to the InvenTree API. The API accepts either basic username:password authentication, or token authentication. Token authentication is recommended as it provides much faster API access.
+
+!!! warning "Permissions"
+    API access is restricted based on the permissions assigned to the user.
+
+### 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.
+
+!!! info "Token Administration"
+    User tokens can be created and/or invalidated via the Admin interface.
+
+### Requesting a Token
+
+If a user does not know their access token, it can be requested via the API interface itself, using a basic authentication request.
+
+To obtain a valid token, perform a GET request to `/api/user/token/`. No data are required, but a valid username / password combination must be supplied in the authentication headers.
 
 !!! info "Credentials"
 	Ensure that a valid username:password combination are supplied as basic authorization headers.
 
+Once a valid token is received from the server, subsequent API requests should be performed using that token.
+
 If the supplied user credentials are validated, the server will respond with:
 
 ```
@@ -30,4 +48,31 @@ HTTP_200_OK
 }
 ```
 
+### Using a Token
+
 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).
+
+**Example: Javascript**
+```javascript
+var token = "MY-TOKEN-VALUE-HERE";
+
+$.ajax({
+  url: "http://localhost:8080/api/part/",
+  type: 'GET',
+  headers: {"Authorization": `Token ${token}`}
+});
+```
+
+**Example: Python (Requests)**
+```python
+import requests
+
+token = 'MY-TOKEN-VALUE-HERE'
+data = { ... }
+headers = {
+    'AUTHORIZATION': f'Token {token}'
+}
+response = request.get('http://localhost:8080/api/part/', data=data, headers=headers)
+```

docs/index.md

@@ -20,44 +20,44 @@ InvenTree is designed to allow for a flexible installation. You could run the In
 
 Parts are the fundamental element of any inventory. InvenTree groups parts into structured categories which allow you to arrange parts to meet your particular needs. 
 
-[Read more...](part/part)
+[Read more...](./part/part)
 
 ### Manage Suppliers
 
 InvenTree allows you to easily create, modify or delete suppliers and supplier items linked to any part in your inventory.
 
-[Read more...](buy/supplier)
+[Read more...](./buy/supplier)
 
 ### Instant Stock Knowledge
 
 Instantly view current stock for a certain part, in a particular location, or required for an individual build. Stock items are organized in cascading locations and sub-locations, allowing flexible inspection of stock under any location. Stock items can be serialized for tracking of individual items, and test results can be stored against a serialized stock item for the purpose of acceptance testing and commissioning.
 
-[Read more...](stock/stock)
+[Read more...](./stock/stock)
 
 ### BOM Management
 
 Intelligent BOM (Bill of Material) management provides a clear understanding of the sub-parts required to make a new part. 
 InvenTree allows you to upload simple BOM files in multiple formats, and download a detailed BOM with all the information stored in its database.
 
-[Read more...](build/bom)
+[Read more...](./build/bom)
 
 ### Build Parts
 
 Inventree features a build management system to help you track the progress of your builds.
 Builds consume stock items to make new parts, you can decide to automatically or manually allocate parts from your current inventory.
 
-[Read more...](build/build)
+[Read more...](./build/build)
 
 ### Report
 
-Generate a wide range of reports using custom templates. [Read more...](docs/report/report)
+Generate a wide range of reports using custom templates. [Read more...](./report/report)
 
 ### 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.
 
-[Read more...](extend/api)
+[Read more...](./extend/api)
 
 ## Getting Started
 
-Refer to the [installation guide](start/install) for instructions on installing InvenTree. The server where InvenTree is to be installed will need to meet some basic package requirements, and a certain level of system administration understanding is assumed.
+Refer to the [installation guide](./start/install) for instructions on installing InvenTree. The server where InvenTree is to be installed will need to meet some basic package requirements, and a certain level of system administration understanding is assumed.

docs/part/part.md

@@ -25,5 +25,5 @@ The category part list provides an overview of each part:
 
 The list of parts underneath a given category can be filtered by multiple user-configurable filters, which is especially useful when a large number of parts exist under a certain category.
 
-Clicking on the part name links to the [*Part Detail*](/part/views) view.
+Clicking on the part name links to the [*Part Detail*](../views) view.
 

docs/part/test.md

@@ -39,4 +39,4 @@ If this flag is set, then a corresponding test result against a stock item must
 
 ### Test Results
 
-Individual stock item objects can have test results associated with them which correspond to test templates. Refer to the [stock test result](/stock/test) documentation for further information.
+Individual stock item objects can have test results associated with them which correspond to test templates. Refer to the [stock test result](../../stock/test) documentation for further information.

docs/part/views.md

@@ -36,15 +36,15 @@ A Part can provide different functionality based on the following options.
 
 **Virtual** - A *Virtual* part is one which does not physically exist but should still be tracked in the system. This could be a process step, machine time, software license, etc.
 
-**Template** - A *Template* part is one which can have *variants* which exist underneath it. [Read further information about template parts here](/part/template).
+**Template** - A *Template* part is one which can have *variants* which exist underneath it. [Read further information about template parts here](../template).
 
-**Assembly** - If a part is designated as an *Assembly* it can be created (or built) from other component parts. As an example, a circuit board assembly is made using multiple electronic components, which are tracked in the system. An *Assembly* Part has a Bill of Materials (BOM) which lists all the required sub-components. [Read further information about BOM management here](/build/bom).
+**Assembly** - If a part is designated as an *Assembly* it can be created (or built) from other component parts. As an example, a circuit board assembly is made using multiple electronic components, which are tracked in the system. An *Assembly* Part has a Bill of Materials (BOM) which lists all the required sub-components. [Read further information about BOM management here](../../build/bom).
 
-**Component** - If a part is designated as a *Component* it can be used as a sub-component of an *Assembly*. [Read further information about BOM management here](/build/bom)
+**Component** - If a part is designated as a *Component* it can be used as a sub-component of an *Assembly*. [Read further information about BOM management here](../../build/bom)
 
 **Trackable** - If a part is designed as *trackable*, it can be tracked using unique serial numbers.
 
-**Purchaseable** - If a part is designated as *Purchaseable* it can be purchased from external suppliers. Setting this flag allows parts to be added to [purchase orders](/buy/po).
+**Purchaseable** - If a part is designated as *Purchaseable* it can be purchased from external suppliers. Setting this flag allows parts to be added to [purchase orders](../../buy/po).
 
 **Salable** - If a part is designated as *Salable* it can be sold to external customers. Setting this flag allows parts to be added to sales orders.
 
@@ -52,13 +52,13 @@ A Part can provide different functionality based on the following options.
 
 ## Parameters
 
-Parts can have multiple defined [parameters](/part/parameter).
+Parts can have multiple defined [parameters](../parameter).
 
 ## Variants
 
 If a part is a *Template Part* then the *Variants* tab will be visible.
 
-[Read about Part templates](/part/template)
+[Read about Part templates](../template)
 
 ## Stock
 
@@ -90,7 +90,7 @@ The *Allocated* tab displays how many units of this part have been allocated to
 
 ## BOM
 
-The *BOM* tab displays the [Bill of Materials](/build/bom) - a list of sub-components used to build an assembly. Each row in the BOM specifies a quantity of another Part which is required to build the assembly. This tab is only visible if the Part is an *assembly* (meaning it can be build from other parts).
+The *BOM* tab displays the [Bill of Materials](../../build/bom) - a list of sub-components used to build an assembly. Each row in the BOM specifies a quantity of another Part which is required to build the assembly. This tab is only visible if the Part is an *assembly* (meaning it can be build from other parts).
 
 ## Build Orders
 
@@ -122,7 +122,7 @@ The *Sales Orders* tab shows a list of the sales orders for this part. It provid
 
 ## Tests
 
-If a part is marked as *trackable*, the user can define tests which must be performed on any stock items which are instances of this part. [Read more about testing](/part/test).
+If a part is marked as *trackable*, the user can define tests which must be performed on any stock items which are instances of this part. [Read more about testing](../test).
 
 ## Attachments
 

docs/report/report.md

@@ -16,9 +16,9 @@ In addition to providing the ability for end-users to provide their own reportin
 
 Following is a list of available report types
 
-* [Test Report](/report/test): Format results of a test report against for a particular StockItem
+* [Test Report](../test): Format results of a test report against for a particular StockItem
-* [Packing List](/report/pack): Format a list of items for shipping or transfer
+* [Packing List](../pack): Format a list of items for shipping or transfer
-* [Order List](/report/order): Order line items 
+* [Order List](../order): Order line items 
 
 ## Template Formats
 

docs/start/install.md

@@ -20,31 +20,54 @@ Database selection should be determined by your particular installation requirem
 
 ### Serving Data
 
-Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](start/deploy).
+Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](./deploy).
 
-## Setup
+## OS Requirements
 
 To install a complete *development* environment for InvenTree, follow the steps presented below. A production environment will require further work as per the particular application requirements. 
 
-!!! warning "Windows"
+Installing and running InvenTree should be possible on most operating systems, as it requires only cross-platform Python libraries.
-    If you are using the Windows operating system, it is recommended that you use the <a href='https://docs.microsoft.com/en-us/windows/wsl/install-win10'>WSL (Windows Subsystem for Linux) framework</a>
 
-### Requirements
+### Linux
 
-To install InvenTree you will need python3 (>3.6) installed, as well as PIP (the Python package manager).
+The InvenTree documentation assumes that the operating system is a Linux variant. To install the required python packages to get started on a Linux system, run the following commands:
-
-Install these required programs (e.g. using apt or similar) before running the setup scripts.
-
-For example:
 
 ```
 sudo apt-get update
-sudo apt-get install python3 python3-dev python3-pip
+sudo apt-get install python3 python3-dev
+sudo apt-get install python3-pip python3-invoke
 ```
 
 !!! warning "Sudo"
     `apt-get` commands will (most likely) be required to run under sudo. Take care not to run the installation scripts under sudo, as this may alter the system python path and cause the InvenTree installation to not work correctly
 
+### Windows
+
+InvenTree can be installed and run from the Windows command line, assuming the following binaries are available in the system PATH:
+
+- python3
+- pip3
+- invoke
+
+!!! info "WSL"
+
+    Alternatively, if you are running under the Windows operating system you can install and run InvenTree using the <a href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">WSL (Windows Subsystem for Linux)</a> framework. Running under WSL provides a Linux compatible layer which simplifies InvenTree installation.
+
+### FreeBSD
+
+If you are running the FreeBSD operating system, run the following commands to install the required Python packages:
+
+```
+pkg install python
+pkg install py37-pip
+pkg install py37-wheel
+pkg install py37-invoke
+```
+
+## Python Setup
+
+To install InvenTree you will need python3 (>3.6) installed, as well as PIP (the Python package manager), and the Invoke tool.
+
 ### Python Virtual Environment
 
 Installing the required Python packages inside a virtual environment allows a local install separate to the system-wide Python installation. While not strictly necessary, using a virtual environment is highly recommended as it prevents conflicts between the different Python installations.
@@ -122,7 +145,7 @@ Once the required packages are installed, the database configuration must be adj
 
 As part of the previous *install* step, a configuration file (**config.yaml**) is created. The configuration file provides administrators control over various setup options without digging into the Django *settings.py* script. The default setup uses a local sqlite database with *DEBUG* mode enabled.
 
-For further information on installation configuration, refer to the [Configuration](start/config) section.
+For further information on installation configuration, refer to the [Configuration](../config) section.
 
 !!! warning "Configure Database"
     Ensure database settings are correctly configured in `config.yaml` before proceeding to the next step!
@@ -167,4 +190,4 @@ This will launch the InvenTree web interface at `http://127.0.0.1:8000`. For oth
 
 ### Run Production Server
 
-For a production install, refer to [deployment instructions](start/deploy).
+For a production install, refer to [deployment instructions](../deploy).

docs/start/migrate.md

@@ -19,13 +19,12 @@ This will export all data (including user information) to a json data file.
 
 ### Initialize New Database
 
-Configure the new database using the normal processes (see [Configuration](start/config))
+Configure the new database using the normal processes (see [Configuration](../config))
 
 Then, ensure that the database schema are correctly initialized in the new database:
 
 ```
-python3 InvenTree/manage.py makemigrations
+invoke migrate
-python3 InvenTree/manage.py migrate --run-syncdb
 ```
 
 ### Import Data
@@ -35,5 +34,6 @@ The new database should now be correctly initialized with the correct table stru
 ```
 python3 InvenTree/manage.py loaddata data.json
 ```
+
 !!! info "Character Encoding"
 	If the character encoding of the data file does not exactly match the target database, the import operation may not succeed. In this case, some manual editing of the database JSON file may be required.

docs/stock/stock.md

@@ -8,7 +8,7 @@ A stock location represents a physical real-world location where *Stock Items* a
 
 ## Stock Item
 
-A *Stock Item* is an actual instance of a [*Part*](/part/part) item. It represents a physical quantity of the *Part* in a specific location.
+A *Stock Item* is an actual instance of a [*Part*](../../part/part) item. It represents a physical quantity of the *Part* in a specific location.
 
 ### Stock Item Details
 

docs/stock/test.md

@@ -6,7 +6,7 @@ title: 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/), against which test data can be uploaded. Additionally, arbitrary test information can be assigned to the stock item.
+The master "Part" record for the stock item can define multiple [test templates](../../part/test/), 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
@@ -44,7 +44,7 @@ Multiple results can be uploaded against the same test name. In cases where mult
 
 ### 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/) or the [InvenTree Python Interface](/extend/python/).
+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/) or the [InvenTree Python Interface](../../extend/python/).
 
 !!! 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.