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

.github/ISSUE_TEMPLATE/documentation.yaml

@@ -0,0 +1,15 @@
+name: "Documentation"
+description: "Create an issue to improve the documentation"
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Create a new issue regarding the InvenTree documentation
+  - type: textarea
+    id: repro
+    attributes:
+      label: Body of the issue
+      description: Please provide one distinct thing to fix or a clearly defined enhancment
+    validations:
+      required: true

.github/workflows/check_docs_config.yaml

@@ -0,0 +1,27 @@
+name: Documentation Config Checks
+
+on:
+  push:
+    branches-ignore:
+      - l10*
+
+  pull_request:
+    branches-ignore:
+      - l10*
+
+jobs:
+
+  mkdocs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Run Checks
+        run: |
+          pip install pyyaml
+          python docs/ci/check_mkdocs_config.py

.gitignore

@@ -45,9 +45,6 @@ inventree/label.png
 inventree/my_special*
 _tests*.txt
 
-# Sphinx files
-docs/_build
-
 # Local static and media file storage (only when running in development mode)
 inventree_media
 inventree_static
@@ -100,7 +97,7 @@ node_modules/
 maintenance_mode_state.txt
 
 # plugin dev directory
-plugins/
+./plugins/
 
 # Compiled translation files
 *.mo

.pre-commit-config.yaml

@@ -12,7 +12,6 @@ repos:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
-    -   id: check-added-large-files
     -   id: mixed-line-ending
 -   repo: https://github.com/pycqa/flake8
     rev: '6.0.0'
@@ -28,7 +27,7 @@ repos:
     hooks:
     -   id: isort
 -   repo: https://github.com/jazzband/pip-tools
-    rev: 6.12.3
+    rev: 6.13.0
     hooks:
       - id: pip-compile
         name: pip-compile requirements-dev.in

CONTRIBUTING.md

@@ -101,7 +101,7 @@ django-upgrade --target-version 3.2 `find . -name "*.py"`
 ```
 
 ## Credits
-If you add any new dependencies / libraries, they need to be added to [the docs](https://github.com/inventree/inventree-docs/blob/master/docs/credits.md). Please try to do that as timely as possible.
+If you add any new dependencies / libraries, they need to be added to [the docs](https://github.com/inventree/inventree/blob/master/docs/docs/credits.md). Please try to do that as timely as possible.
 
 
 ## Migration Files
@@ -130,7 +130,7 @@ Please write docstrings for each function and class - we follow the [google doc-
 
 ## Documentation
 
-New features or updates to existing features should be accompanied by user documentation. A PR with associated documentation should link to the matching PR at https://github.com/inventree/inventree-docs/
+New features or updates to existing features should be accompanied by user documentation.
 
 ## Translations
 

RELEASE.md

@@ -14,10 +14,6 @@ If the API has changed, ensure that the API version number is incremented.
 
 Merge the crowdin translation updates into master branch
 
-### Documentation Release
-
-Create new release for the [InvenTree documentation](https://github.com/inventree/inventree-docs)
-
 ### Python Library Release
 
 Create new release for the [InvenTree python library](https://github.com/inventree/inventree-python)

docs/.gitignore

@@ -0,0 +1,15 @@
+# Ignore python environment files
+env-inv-doc/
+env/
+
+# Compiled python files
+*.pyd
+*.pyc
+
+# Sphinx files
+_build
+
+# Temp files
+releases.json
+
+.vscode/

docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 InvenTree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/README.md

@@ -0,0 +1,84 @@
+# InvenTree Documentation
+
+[![Documentation Status](https://readthedocs.org/projects/inventree/badge/?version=latest)](https://inventree.readthedocs.io/en/latest/?badge=latest)
+
+This repository hosts the [official documentation](https://inventree.readthedocs.io/) for [InvenTree](https://github.com/inventree/inventree), an open source inventory management system.
+
+To serve this documentation locally (e.g. for development), you will need to have Python 3 installed on your system.
+
+## Setup
+
+Run the following commands from the top-level project directory:
+
+```
+$ git clone https://github.com/inventree/inventree
+$ cd inventree/docs
+$ pip install -r requirements.txt
+```
+
+## Serve Locally
+
+To serve the pages locally, run the following command (from the top-level project directory):
+
+```
+$ mkdocs serve -a localhost:8080
+```
+
+## Edit Documentation Files
+
+Once the server is running, it will monitor the documentation files for any changes, and update the served pages.
+
+### Admonitions
+
+"Admonition" blocks can be added as follow:
+```
+!!! info "This is the admonition block title"
+    This is the admonition block content
+```
+
+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.
+
+Also, linking to an internal page must use the `.md` suffix!
+
+For example, to link to the page `/part/views` from `/stock/stocktake`, the link must be formed as follows:
+
+```
+Click [here](../part/views.md)
+```
+
+*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:
+```
+{% with id="image_id", url="folder/image_name.png", description="Text shown if image is not loaded properly" %}
+{% include 'img.html' %}
+{% endwith %}
+```
+
+Replace:
+* `image_id` with a short unique indentifier for the image (most commonly, `image_id` is same as `image_name`)
+* `folder` with the folder in `docs/assets/images` in which the image is stored
+* `image_name` with the name of the image
+* `.png` with the image extension (PNG or JPEG are preferred formats)
+
+### Global variables
+
+Refer to the [reference documentation](https://squidfunk.github.io/mkdocs-material/reference/variables/#using-custom-variables) to find out how to add global variables to the documentation site.
+
+Global variables should be added in the `# Global Variables` section of the `mkdocs.yml` configuration file.
+
+## Credits
+
+This documentation makes use of the [mkdocs-material template](https://github.com/squidfunk/mkdocs-material)

docs/_includes/app_img.html

@@ -0,0 +1,5 @@
+{% set url = 'app/' + url %}
+
+{% with id=id, url=url, maxheight="240px", description="" %}
+{% include "img.html" %}
+{% endwith %}

docs/_includes/carousel.html

@@ -0,0 +1,32 @@
+<div class='splide'>
+    <div class='splide__track'>
+        <ul class='splide__list'>
+            {% for img in listimages(directory) %}
+            {% with src=img %}
+            {% include "splide_image.html" %}
+            {% endwith %}
+            {% endfor %}
+        </ul>
+    </div>
+</div>
+
+<script>
+	document.addEventListener( 'DOMContentLoaded', function () {
+		new Splide(
+            '.splide', {
+                type: 'loop',
+                perPage: {{ per_page }},
+                autoplay: true,
+                pagination: false,
+                // cover: true,
+                // autoWidth: true,
+                height: '25rem',
+                focus: 'center',
+                padding: {
+                    left: '5rem',
+                    right: '5rem',
+                }
+            }
+        ).mount();
+	} );
+</script>

docs/_includes/gunicorn.conf.py

@@ -0,0 +1,5 @@
+import multiprocessing
+
+bind = "0.0.0.0:8000"
+
+workers = multiprocessing.cpu_count() * 2 + 1

docs/_includes/img.html

@@ -0,0 +1,30 @@
+{% if 'http' in url %}
+{% set img_url = url %}
+{% else %}
+{% set img_url = config.assets_dir  + '/images/' + url %}
+{% endif %}
+
+<figure class='image image-inventree'>
+    {% if id %}
+    <!-- The link that, when clicked, will display the image in full screen -->
+    <a href="#{{ id }}">
+    {% elif img_url %}
+    <a href="{{ img_url }}">
+    {% endif %}
+        <img class='img-inline' src='{{ img_url }}' alt='{{ description }}' title='{{ description }}'
+        {% if maxwidth or maxheight %}style='
+        {% if maxwidth %} max-width:{{ maxwidth }};{% endif %}
+        {% if maxheight %} max-height: {{ maxheight }};{% endif %}
+        '{% endif %}
+        >
+    {% if id or img_url %}
+    </a>
+    {% endif %}
+
+    {% if id %}
+    <!-- The full screen image, hidden by default  -->
+    <a href="#_" class="overlay" id="{{ id }}">
+      <img src="{{ img_url }}" alt="{{ description }}" />
+    </a>
+    {% endif %}
+</figure>

docs/_includes/overrides/404.html

@@ -0,0 +1,29 @@
+{% extends "base.html" %}
+
+{% block tabs %}
+{{ super() }}
+
+{% endblock %}
+
+{% block site_nav %}
+{% endblock %}
+
+{% block content %}
+<style>
+  h1 {
+    font-family: Arial, Helvetica, sans-serif;
+    display: block;
+  }
+</style>
+
+<section class="mdx-container">
+  <div class="md-grid md-typeset">
+    <div class="mdx-hero"></div>
+      <h1>
+        <span class='fas fa-search'></span>
+        Page not found
+      </h1>
+  </div>
+</section>
+
+{% endblock %}

docs/_includes/overrides/home.html

@@ -0,0 +1,47 @@
+{% extends "main.html" %}
+
+{% block tabs %}
+{{ super() }}
+
+{% endblock %}
+
+{% block content %}
+
+{{ page.content }}
+
+<style>
+    h1 {
+        font-family: Arial, Helvetica, sans-serif;
+    }
+</style>
+
+<!-- Hero for landing page -->
+<section class="mdx-container">
+    <div class="md-grid md-typeset">
+      <div class="mdx-hero">
+
+        <!-- Hero content -->
+        <div class="mdx-hero__content">
+
+          <a href="https://inventree.org" title="InvenTree Website" class="md-button">
+            <span class='fas fa-globe'></span> Website
+          </a>
+
+          <a href="start/intro" title="Install InvenTree" class="md-button">
+            <span class='fas fa-server'></span> Install
+          </a>
+          <a href="app/app" title="InvenTree mobile app" class="md-button">
+            <span class='fas fa-mobile-alt'></span> Mobile App
+          </a>
+          <a href="https://crowdin.com/project/inventree" title="Help translate InvenTree" class="md-button">
+            <span class='fas fa-language'></span> Translate
+          </a>
+          <a href="https://github.com/inventree/inventree" title="Explore InvenTree source code" class="md-button md-button">
+            <span class='fab fa-github'></span> Source Code
+          </a>
+        </div>
+      </div>
+    </div>
+  </section>
+
+{% endblock %}

docs/_includes/overrides/main.html

@@ -0,0 +1,6 @@
+{% extends "base.html" %}
+
+{% block header %}
+{% include "partials/version_banner.html" %}
+{% include "partials/header.html" %}
+{% endblock %}

docs/_includes/overrides/partials/outdated.html

@@ -0,0 +1 @@
+<!-- Empty "outdated" warning, we will handle this in 'banner.html' -->

docs/_includes/overrides/partials/version_banner.html

@@ -0,0 +1,15 @@
+{% if config.version_banner %}
+<div class='alert alert-warning alert-dismissable alert-version' role='alert'>
+    <div class='md-grid md-typeset'>
+        <small>
+        {% if config.readthedocs.version == 'latest' %}
+            This documentation is for the <em>development</em> version of InvenTree, which may be significantly different from the stable releases.
+        {% else %}
+            This documentation is for an outdated version of InvenTree.
+        {% endif %}
+        For <em>stable</em> release documentation, use the version selector located in the bottom right corner of this page.
+        </small>
+        <button type="button" class="close" data-dismiss="alert" aria-label="Close"><span aria-hidden="true">&times;</span></button>
+    </div>
+</div>
+{% endif %}

docs/_includes/release_table.html

@@ -0,0 +1,29 @@
+
+<tr>
+    <td colspan='2'><b><i>Release {{ prefix }}.x</i></b></td>
+    <td colspan='2'></td>
+</tr>
+{% for release in config.releases %}
+{% if release.prefix == prefix %}
+<tr>
+    <td>
+        {% if release.local_path %}
+        <a href="../{{ release.tag_name }}">{{ release.tag_name }}</a>
+        {% else %}
+        {{ release.tag_name }}
+        {% endif %}
+    </td>
+    <td>{{ release.date }}</td>
+    <td>
+        <a href="https://github.com/inventree/InvenTree/releases/tag/{{ release.tag_name }}">{{ release.tag_name }}</a>
+    </td>
+    <td>
+        {% if release.docker %}
+        <a href="https://hub.docker.com/r/inventree/inventree/tags">inventree/inventree:{{ release.tag_name }}</a>
+        {% else %}
+        <em>Not available for this release</em>
+        {% endif %}
+    </td>
+</tr>
+{% endif %}
+{% endfor %}

docs/_includes/release_table_head.html

@@ -0,0 +1,13 @@
+
+<div class='md-typeset__scrollwrap'>
+    <div class='md-typeset__table'>
+        <table>
+            <thead>
+                <tr>
+                    <th><span class='fas fa-clipboard-list'></span> Release</th>
+                    <th><span class='fas fa-calendar-alt'></span> Date</th>
+                    <th><span class='fab fa-github'></span> GitHub</th>
+                    <th><span class='fab fa-docker'></span> Docker</th>
+                </tr>
+            </thead>
+            <tbody>

docs/_includes/release_table_tail.html

@@ -0,0 +1,4 @@
+</tbody>
+</table>
+</div>
+</div>

docs/_includes/splide_image.html

@@ -0,0 +1,10 @@
+
+{% if 'http' in src %}
+{% set img_url = src %}
+{% else %}
+{% set img_url = config.assets_dir  + '/images/' + src %}
+{% endif %}
+
+<li class='splide__slide'>
+    <img src='{{ img_url }}'>
+</li>

docs/ci/check_mkdocs_config.py

@@ -0,0 +1,16 @@
+"""Check mkdocs.yml config file for errors."""
+
+import os
+
+import yaml
+
+here = os.path.dirname(__file__)
+
+tld = os.path.abspath(os.path.join(here, '..'))
+
+config_file = os.path.join(tld, 'mkdocs.yml')
+
+with open(config_file, 'r') as f:
+    data = yaml.safe_load(f)
+
+    assert data['strict'] is True

docs/docs/api/api.md

@@ -0,0 +1,110 @@
+---
+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.
+
+!!! info "Django REST Framework"
+    The InvenTree API is based on the powerful and flexible [Django REST Framework](https://www.django-rest-framework.org/).
+
+## 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/`
+
+{% with id="api_doc", url="api/api_doc.png", description="API documentation" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## Authentication
+
+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.
+
+### 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.
+
+!!! 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:
+
+```
+HTTP_200_OK
+{
+    token: "usertokendatastring",
+}
+```
+
+### 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)
+```
+
+## Authorization
+
+### User Roles
+
+Users can only perform REST API actions which align with their assigned [role permissions](../settings/permissions.md#roles).
+Once a user has *authenticated* via the API, a list of the available roles can be retrieved from:
+
+`/api/user/roles/`
+
+For example, when accessing the API from a *superuser* account:
+
+{% with id="api_roles", url="api/api_roles.png", description="API superuser roles" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Or, when accessing the API from an account which has read-only permissions:
+
+{% with id="api_roles_2", url="api/api_roles_2.png", description="API user roles" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Permission Denied
+
+If an API action outside of the user's role(s) is attempted, the server will respond with a 403 permission error message.

docs/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/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/docs/api/download.md

@@ -0,0 +1,22 @@
+---
+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/docs/api/metadata.md

@@ -0,0 +1,91 @@
+---
+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](https://crowdin.com/project/inventree). 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/docs/api/python/currency.md

@@ -0,0 +1,56 @@
+---
+title: Python Currency Support
+---
+
+## Currency Support
+
+InvenTree provides native support for multiple currencies, which can mean that data require conversion between these currencies, at defined exchange rates.
+
+The InvenTree server maintains a set of exchange rates, which are updated periodically. These exchange rates are available via the [InvenTree API](../api.md), and can be used by the Python bindings.
+
+### CurrencyManager Class
+
+The Python bindings provide the `CurrencyManager` class, which takes care of retrieving currency exchange data from the server. This class can be instantiated as shown below:
+
+```python
+from inventree.currency import CurrencyManager
+
+# The manager class must be passed a valid InvenTreeAPI instance
+manager = CurrencyManager(api)
+
+# Access the 'base currency' data
+base_currency = manager.getBaseCurrency()
+
+# Access the 'exchange rate' data
+rates = manager.getExchangeRates()
+```
+
+### Currency Conversion
+
+Currency conversion is performed by passing the value of currency, as well as the *source* and *target* currency codes to the currency manager.
+
+!!! warning "Missing Currency Data"
+    The currency conversion only works if the manager class has valid information on both the *source* and *target* currency exchange rates!
+
+```python
+from inventree.currency import CurrencyManager
+
+manager = CurrencyManager(api)
+
+# Convert from AUD to CAD
+cad = manager.convertCurrency(12.54, 'AUD', 'CAD')
+
+# Convert from NZD to USD
+usd = manager.convertCurrency(99.99, 'NZD', 'USD')
+```
+
+### Exchange Rate Update
+
+To request a manual update of currency data (from the server), run the following command:
+
+```python
+from inventree.currency import CurrencyManager
+
+manager = CurrencyManager(api)
+manager.refreshExchangeRates()
+```

docs/docs/api/python/examples.md

@@ -0,0 +1,224 @@
+---
+title: Python Interface 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
+
+Use the `create` method to add new items to the database:
+
+```python
+from inventree.part import Part, PartCategory
+from inventree.stock import StockItem
+
+## Create a new PartCategory object,
+## underneath the existing category with pk 7. Leave the parent empty fpr a top level category
+furniture = PartCategory.create(api, {
+    'name': 'Furniture',
+    'description': 'Chairs, tables, etc',
+    'parent': 7,
+})
+
+## Create a new Part
+## Use the pk (primary-key) of the newly created category
+couch = Part.create(api, {
+    'name': 'Couch',
+    'description': 'Long thing for sitting on',
+    'category': furniture.pk,
+    'active': True,
+    'virtual': False,
+    ## Note - You do not have to fill out *all* fields
+})
+```
+
+### 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:
+
+```python
+from inventree.api import InvenTreeAPI
+from inventree.part import Part
+
+api = InvenTreeAPI(host='http://localhost:8000', username='admin', password='inventree')
+
+# Retrieve part instance with primary-key of 1
+part = Part(api, pk=1)
+
+# Update specified part parameters
+part.save(data={
+    "description": "New part description",
+    "minimum_stock": 250,
+})
+
+# Reload data from remote server
+part.reload()
+
+# Display updated data
+print("Part Name:", part.name)
+print("Description:", part.description)
+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
+
+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
+from inventree.part import ParameterTemplate
+
+LengthTemplate = ParameterTemplate.create(api, { 'name' : 'Length', 'units' : 'Meters' })
+WeightTemplate = ParameterTemplate.create(api, { 'name' : 'Weight', 'units' : 'kg' })
+
+ParameterLength = Parameter.create(api, { 'part': couch.pk, 'template': LengthTemplate.pk, 'data' : 2 })
+ParameterWeight = Parameter.create(api, { 'part': couch.pk, 'template': WeightTemplate.pk, 'data' : 60 })
+```
+These parameter templates need to be defined only once and can be used for all other parts. Lets finally add a picture.
+
+```python
+couch.upload_image('my_nice_couch.jpg')
+```
+
+### 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.
+
+```python
+
+from inventree.stock import StockLocation
+from inventree.stock import StockItem
+
+...
+
+## Create the stock locations. Leave the parent empty for top level hierarchy
+Aisle3 = StockLocation.create(api, {'name':'Aisle 3','description':'Aisle for sofas','parent':''})
+Shelve43 = StockLocation.create(api, {'name':'Shelve 43','description':'Shelve for sofas','parent':Aisle3.pk})
+Box12 = StockLocation.create(api, {'name':'Box 12','description':'green box','parent':Shelve43.pk})
+Box13 = StockLocation.create(api, {'name':'Box 13','description':'red box','parent':Shelve43.pk})
+
+## Now fill them with items
+Id1 = StockItem.create(api, { 'part': sofa.pk, 'quantity': 10, 'notes': 'new ones', 'location': Box12.pk, ‘status’:10 })
+Id2 = StockItem.create(api, { 'part': sofa.pk, 'quantity': 3, 'notes': 'old ones', 'location': Box13.pk, ‘status’:55 })
+
+```
+Please recognize the different status flags. 10 means OK, 55 means damaged. We have the following choices:
+
+* 10: OK
+* 50: Attention needed
+* 55: Damaged
+* 60: Destroyed
+* 65: Rejected
+* 70: Lost
+* 85: Returned
+
+### 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).
+
+```python
+from inventree.company import Company
+
+...
+
+acme = Company.create(api, {
+    'name' : 'ACME',
+    'description':'A Company that makes everything',
+    'website':'https://www.acme.bla',
+    'is_customer':0,
+    'is_manufacturer':1,
+    'is_supplier':0
+})
+xstore = Company.create(api, {
+    'name' : 'X-Store',
+    'description':'A really cool online store',
+    'website':'https://www.xst.bla',
+    'is_customer':0,
+    'is_manufacturer':0,
+    'is_supplier':1
+})
+```
+
+Please recognize the different flag settings for is_supplier and is_manufacturer. Now lets add those to our couch:
+
+```python
+from inventree.company import SupplierPart
+
+...
+
+SupplierPart.create(api,{
+    'part':couch.pk,
+    'supplier':xstore.pk,
+    'SKU':'some_code',
+    'link':'https://www.xst.bla/products/stock?...'
+})
+ManufacturerPart.create(api,{
+    'part':couch.pk,
+    'manufacturer':acme.pk,
+    'MPN':'Part code of the manufacturer'
+})
+```
+
+### Stock Adjustments
+
+Various stock adjustment actions can be performed as follows:
+
+```python
+from inventree.stock import StockItem, StockLocation
+
+# Fetch item from the server
+item = StockItem(api, pk=99)
+
+# Count stock
+item.countStock(500)
+
+# Add stock to the item
+item.addStock(15)
+
+# Remove stock from the item
+item.removeStock(25)
+
+# Transfer partial quantity to another location
+loc = StockLocation(api, pk=12)
+item.transferStock(loc, quantity=50)
+```
+
+### Bulk Delete
+
+Some database models support bulk delete operations, where multiple database entries can be deleted in a single API query.
+
+```python
+from inventree.stock import StockItem
+
+# Delete all items in a particular category
+StockItem.bulkDelete(api, filters={'category': 3})
+```
+
+### 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:
+
+```python
+from inventree.part import PartAttachment
+
+# The ID of the Part to attach the files to
+part_id = 47
+
+PartAttachment.upload(api, part_id, 'manual.pdf', comment='Datasheet')
+PartAttachment.upload(api, part_id, 'sofa.dxf', comment='Drawing')
+```
+
+Alternatively, we can upload an attachment directly against the `Part` instance:
+
+```python
+from inventree.part import Part
+
+part = Part(api, pk=47)
+
+part.uploadAttachment('data.txt', comment='A data file')
+```

docs/docs/api/python/python.md

@@ -0,0 +1,167 @@
+---
+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.
+
+#### Filtering by parent
+
+In tree based models the child items could be filtered by using the parent keyword:
+
+```python
+from inventree.part import PartCategory
+
+child_categories = PartCategory.list(api, parent=10)
+```
+
+The top level items can can be queried by passing empty string as a parent filter:
+
+```python
+from inventree.part import PartCategory
+
+parent_categories = PartCategory.list(api, parent='')
+```
+
+### 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/docs/app/app.md

@@ -0,0 +1,33 @@
+---
+title: InvenTree Mobile App
+---
+
+{% with directory="appgallery", per_page=2 %}
+{% include "carousel.html" %}
+{% endwith %}
+
+-----
+
+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.
+
+## Features
+
+- View and edit part and stock information with a blazingly fast interface
+- Perform stock control actions on the go
+- Barcode integrations simply stock operations
+- Receive purchase orders and check in stock items
+- And many more!
+
+## Download
+
+The InvenTree app can be downloaded from either the Android or Apple app stores, or accessed via the links below:
+
+### Android
+
+<span class='fab fa-android'></span> [Android Play Store](https://play.google.com/store/apps/details?id=inventree.inventree_app).
+
+### iOS
+
+<span class='fab fa-apple'></span> [Apple App Store](https://apps.apple.com/au/app/inventree/id1581731101#?platform=iphone)

docs/docs/app/barcode.md

@@ -0,0 +1,32 @@
+---
+title: App Barcode Support
+---
+
+## Barcode Support
+
+One of the key elements of functionality provided by the InvenTree app is the native support for context-sensitive barcode scanning.
+
+Barcode integration allows extremely efficient stock control, for information lookup and also performing various actions.
+
+### Supported Codes
+
+The following code types are known to be supported
+
+**1D Codes**
+
+- Code-39
+- Code-93
+- Code-128
+- ITF
+
+**2D Codes**
+
+- QR Code
+- Data Matrix
+- Aztec
+
+## Actions
+
+The InvenTree app uses barcodes where possible to provide efficient stock control operations.
+
+If there is a new barcode feature you would like to see, [let us know on GitHub](https://github.com/inventree/InvenTree/issues?q=is%3Aopen+is%3Aissue+label%3Aapp)!

docs/docs/app/connect.md

@@ -0,0 +1,68 @@
+---
+title: Connect to Server
+---
+
+## Connect to InvenTree
+
+Use of the InvenTree app assumes that you (the user) have access to an InvenTree server.
+
+When first running the app, no profile has been configured. The *server* icon in the top-right corner of the home screen is <span style='color: red'>red</span>, indicating that there is no connection to an InvenTree server:
+
+{% with id="no_server", url="app/initial.png", maxheight="240px", description="No server configured" %}
+{% include "img.html" %}
+{% endwith %}
+
+Press on the server icon to navigate to the server selection view:
+
+{% with id="no_profiles", url="app/no_profiles.png", maxheight="240px", description="No server configured" %}
+{% include "img.html" %}
+{% endwith %}
+
+
+### Create Server
+
+!!! success "Server Profiles"
+    The app supports multiple server profiles, providing simple switching between different InvenTree servers and/or account profiles.
+
+Press the <span class='fas fa-plus-circle blue'></span> button in the bottom-right corner of the screen to create a new server profile.
+
+{% with id="add_profile", url="app/add_server_profile.png", maxheight="240px", description="Add server" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Enter the required server details:
+
+| Parameter | Description |
+| --- | --- |
+| **Name** | Name for the server profile (can be any value, simply for reference) |
+| **Server** | InvenTree server address (including port, if required). e.g. `http://inventree.myserver.com:8080` |
+| **Username** | Your account username (case sensitive) |
+| **Password** | Your account password (case sensitive) |
+
+### Connect to Server
+
+Once the server profile is created, you need to connect to the server. Simply short press on the server profile to connect.
+
+Alternatively, long press on the server profile to activate the context menu, then select *Connect to Server*.
+
+When the app successfully connects to the server, a success message is briefly displayed at the bottom of the screen. A green <span class='fas fa-check-circle green'></span> icon next to the server profile indicate that the profile is currently *selected* and also the connection was successful.
+
+{% with id="connected", url="app/connected.png", maxheight="240px", description="Connected to server" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Connection Failure
+
+If (for whatever reason) the app does not successfully connect to the InvenTree server, a failure message is displayed, and a red <span class='fas fa-times-circle red'></span> icon is displayed next to the server profile.
+
+{% with id="failed", url="app/unauthorized.png", maxheight="240px", description="Connection failure" %}
+{% include 'img.html' %}
+{% endwith %}
+
+In this case, the error message displayed at the bottom of the screen provides context as to why the app could not successfully connect to the server.
+
+To edit the server profile details, long press on the server profile, and select *Edit Server Profile*:
+
+{% with id="edit", url="app/edit_server.png", maxheight="240px", description="Edit server profile" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/app/issues.md

@@ -0,0 +1,9 @@
+---
+title: App Suggestions / Issues
+---
+
+## Suggestions / Issues
+
+To suggest an improvement or new feature for the InvenTree app, or to report an issue, refer to the [InvenTree GitHub page](https://github.com/inventree/inventree-app/issues).
+
+General feedback on the app is also welcomed - if you have any ideas on how to make the app more functional or effective, please let us know!

docs/docs/app/navigation.md

@@ -0,0 +1,62 @@
+---
+title: App Navigation
+---
+
+
+## Home Screen
+
+The app *home screen* provides quick-access buttons for stock view and actions:
+
+{% with id="home", url="app/home.png", maxheight="240px", description="Home screen" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## Tab Display
+
+Some screens provide multiple tabbed views, which are displayed at the top of the screen:
+
+{% with id="global_nav", url="app/app_tabs.png", maxheight="240px", description="App tabs" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Tabs can be navigated by pressing on the text of each tab, or by scrolling the screen left or right.
+
+## Global Actions
+
+The *Global Action* buttons are visible on most screens, displayed in the bottom left corner of the screen:
+
+{% with id="global_nav", url="app/app_global_navigation.png", maxheight="240px", description="Global navigation actions" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Open Drawer Menu
+
+The <span class='fas fa-list'></span> action opens the *Drawer Menu*, which is a quick-access menu for global navigation:
+
+{% with id="drawer", url="app/drawer.png", maxheight="240px", description="Open drawer menu" %}
+{% include 'img.html' %}
+{% endwith %}
+
+The *Drawer Menu* can be accessed in the following ways:
+
+- From the *Home Screen* select the *Drawer* icon in the top-left corner of the screen
+- From any other screen, long-press the *Back* button in the top-left corner of the screen
+
+### Search
+
+The <span class='fas fa-search'></span> action opens the [Search](./search.md) screen
+
+### Scan Barcode
+
+The <span class='fas fa-qrcode'></span> action opens the [barcode scan](./barcode.md) window, which allows quick access to the barcode scanning functionality.
+
+## Context Actions
+
+Within a given view, certain context actions may be available. If there are contextual actions which can be performed, they are displayed in the bottom right corner:
+
+{% with id="drawer", url="app/context_actions.png", maxheight="240px", description="Context actions" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! tip "Barcode Actions"
+    Available barcode actions are displayed in a separate context action menu

docs/docs/app/part.md

@@ -0,0 +1,157 @@
+---
+title: Part Views
+---
+
+## Part Category View
+
+From the *home screen*, select *Parts* to open the top-level part category view.
+
+### Details Tab
+
+The *Details* tab shows information about the selected part category. In particular, it shows the name and description of the category, a link to the parent category (if available) and a list of subcategories.
+
+{% with id="part-category", url="part_category_detail.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Parent Category
+
+If the current category has a parent category (i.e. it is not a top-level category) then a link is provided to the parent category. Tap the *parent category* tile to navigate to the category detail page for the parent category.
+
+#### Subcategories
+
+If the current category has any subcategories, these are listed here. Select any of the subcategories to navigate to it.
+
+### Parts Tab
+
+The *Parts* tab displays all the parts available in this category. Tap a displayed part to navigate to the part detail view.
+
+{% with id="cat-parts", url="category_parts_tab.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+The list of available parts can be filtered using the input box at the top of the screen:
+
+{% with id="cat-parts-filter", url="category_parts_filter.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+### Context Actions
+
+The following *Context Actions* are available for the selected category:
+
+{% with id="cat-actions", url="category_actions_tab.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### New Category
+
+Create a new subcategory under the current category:
+
+{% with id="cat-new-cat", url="new_category.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### New Part
+
+Create a new part within the current category:
+
+{% with id="cat-new-part", url="new_part.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+### Edit Category
+
+Select the *Edit* button in the top right corner of the screen to edit the details for the selected part category:
+
+{% with id="cat-edit", url="part_category_edit.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+!!! info "Permission Required"
+    If the user does not have permission to edit part details, this button will be hidden
+
+In the part category display screen, there are three tabs of information available:
+
+## Part Detail View
+
+The *Part Detail* view displays information about a single part:
+
+{% with id="part-details", url="part_details.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+### Details Tab
+
+The *details* tab shows information about the selected part. Some of the displayed tiles provide further information when selected:
+
+#### Category
+
+Tap on the displayed part category to navigate to a detail view for that category.
+
+#### Stock
+
+The *stock* tile shows the total quantity of stock available for the part. Tap on this tile to navigate to the *Stock Tab* view for this part.
+
+#### Notes
+
+Tap on the *notes* tile to view (and edit) the notes for this part:
+
+{% with id="part-notes", url="part_notes.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Attachments
+
+Tap on the *attachments* tile to view the file attachments for this part:
+
+{% with id="part-attachments", url="part_attachments.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+New attachments can be uploaded by tapping on the icons in the top right of the screen.
+
+Select a particular attachment file to downloaded it to the local device.
+
+### Stock Tab
+
+The *Stock* tab displays all the stock items available for this part. Tap on a particular stock item to navigate to a detail view for that item.
+
+{% with id="part-stock", url="part_stock.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+The list of available stock items can be filtered using the input box at the top of the screen.
+
+### Actions Tab
+
+The *Actions* tab displays the available actions for the selected part:
+
+#### New Stock Item
+
+Create a new stock item for this part:
+
+{% with id="part-stock-new", url="new_stock_item.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+### Edit Part
+
+To edit the part details, select the *Edit* button in the top right corner of the screen:
+
+{% with id="part-edit", url="part_edit.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+!!! info "Permission Required"
+    If the user does not have permission to edit part details, this button will be hidden
+
+### Part Image View
+
+Tap the image of the part (displayed at the top left of the screen) to launch the part image view:
+
+{% with id="part-image", url="part_image.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+A full-screen view of the image is displayed. The user can also upload a new image for the part, either selecting an image from the device, or taking a new picture with the device's camera.

docs/docs/app/po.md

@@ -0,0 +1,49 @@
+---
+title: Purchase Orders
+---
+
+## Purchase Order List
+
+The purchase order list display shows all current *outstanding* purchase orders. (Purchase orders which have been completed are not shown here).
+
+{% with id="po_list", url="app/po_list.png", maxheight="240px", description="Purchase order list" %}
+{% include "img.html" %}
+{% endwith %}
+
+Select an individual purchase order to display the detail view for that order.
+
+### Filtering
+
+Available purchase orders can be subsequently filtered using the search input at the top of the screen
+
+## Purchase Order Detail
+
+{% with id="po_detail", url="app/po_detail.png", maxheight="240px", description="Purchase order details" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Edit Order Details
+
+From the detail view, select the *Edit* button in the top-right of the screen. This opens the purchase order editing display:
+
+{% with id="edit_po", url="app/po_edit.png", maxheight="240px", description="Edit purchase order" %}
+{% include "img.html" %}
+{% endwith %}
+
+### Line Items
+
+The *Line Items* tab shows the line items associated with this purchase order:
+
+{% with id="po_lines", url="app/po_lines.png", maxheight="240px", description="Purchase order line items" %}
+{% include "img.html" %}
+{% endwith %}
+
+Long press on a particular line item to receive the item into stock.
+
+### Stock Items
+
+Once items have been received into stock against a particular purchase order, they are displayed in the *Stock Items* tab:
+
+{% with id="po_stock", url="app/po_stock.png", maxheight="240px", description="Purchase order stock items" %}
+{% include "img.html" %}
+{% endwith %}

docs/docs/app/privacy.md

@@ -0,0 +1,46 @@
+---
+title: Privacy Statement
+---
+
+## InvenTree App Privacy Policy
+
+The InvenTree mobile app requires some extra permissions for complete functionality. Additionally, some user information is stored locally on the device where the app is installed.
+
+## Data Collection
+
+### User Profiles
+
+The InvenTree app requires the user to enter profile data to connect with an InvenTree server:
+
+- Server address
+- Account username
+- Account password
+
+Profile data is stored locally on the device, and can be deleted by the user if they wish. Profile data is only used for connection with an InvenTree server.
+
+### Camera Permissions
+
+The InvenTree app requires permission to access the device camera for the following purposes:
+
+- Scanning barcode data
+- Taking pictures with the device camera for upload to connected InvenTree server
+
+Pictures taken in the InvenTree app are not stored or distributed to any other services.
+
+## Personal Information
+
+The InvenTree app does not collect any information which could be used to personally identify the user(s) of the device onto which the app is installed.
+
+## Third Party Access
+
+The InvenTree app does not share any personal information on users of the app with any third parties.
+
+## Error Logs
+
+The InvenTree app makes use of the [sentry.io](https://sentry.io/) service to monitor the app for bugs and run-time errors. When an error occurs in the app, log data is uploaded to the sentry server, where InvenTree developers can use this information to improve the quality of the app.
+
+!!! question "Identifying Information"
+    The uploaded error reports contain information on the nature of the error / bug; i.e. "where" in the app code the failures occured. The uploaded data does not contain any information which can be used to identify users or extract user data.
+
+!!! tip "Disable Error Reporting"
+    If desired, users can disable error reporting entirely, from within the [app settings](./settings.md). This prevents any error logs from being uploaded to the sentry server.

docs/docs/app/search.md

@@ -0,0 +1,15 @@
+---
+title: App Search
+---
+
+## Search Screen
+
+The global search screen provides quick search functionality across the connected InvenTree database. Entering a search term will return multiple search results, as shown in the examples below:
+
+{% with id="search_1", url="app/search_1.png", maxheight="240px", description="Search results" %}
+{% include 'img.html' %}
+{% endwith %}
+
+{% with id="search_2", url="app/search_2.png", maxheight="240px", description="Search results" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/app/settings.md

@@ -0,0 +1,62 @@
+---
+title: App Settings
+---
+
+## Settings
+
+The *Settings* view provides access to user configurable settings, in addition to information about the app itself.
+
+The main settings view is shown below, and provides the following options:
+
+- **Server** - Configure and select server profile
+- **App Settings** - Configure app settings
+- **Home Screen** - Configure home screen settings
+- **Part** - Configure part settings
+- **About** - Display  app version information
+
+{% with id="settings_view", url="app/settings.png", maxheight="240px", description="Settings view" %}
+{% include 'img.html' %}
+{% endwith %}
+
+## App Settings
+
+The *App Settings* view provides configuration options for the InvenTree app:
+
+{% with id="app_settings", url="app/app_settings.png", maxheight="240px", description="App Settings" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Parts
+
+Configure options for "parts" display:
+
+- **Include Subcategories** - When viewing a list of parts in a category, include parts from subcategories
+
+### Stock
+
+Configure options for "stock" display:
+
+- **Include Sublocations** - When viewing a list of stock items in a location, include items from sublocations
+- **Stock History** - Display stock item history in the stock detail view
+
+### Sounds
+
+Configure audible app notifications:
+
+- **Server Error** - Play an audible tone when a server error occurs
+- **Barcode Tones** - Play audible tones when scanning barcodes
+
+### App Settings
+
+- **Dark Mode** - Enable "dark mode" display for the app.
+- **Use Strict HTTPS** - Enforce strict checking of HTTPs certificates. Enabling this option may prevent you from connecting to the server if there are certificate issues.
+- **Language** - Select app language. By default, will use the system language of the device the app is installed on.
+- **Upload Error Reports** - Enable uploading of anonymous error / crash reports. These reports are used to improve the quality of the app.
+
+## Home Screen
+
+The *Home Screen* view allows you to configure display options for the app 'home screen':
+
+{% with id="home_settings", url="app/home_settings.png", maxheight="240px", description="Home Screen Settings" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/app/stock.md

@@ -0,0 +1,171 @@
+---
+title: Stock Views
+---
+
+## Stock Location View
+
+From the *home screen*, select *Stock* to open the top-level stock location view.
+
+### Details Tab
+
+The *Details* tab shows information about the selected stock location.
+
+{% with id="loc-detail", url="location_detail.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Parent Location
+
+If the current location has a parent location (i.e. it is not a top-level location) then a link is provided to the parent location. Tap the *parent location* tile to navigate to the location detail page for the parent location.
+
+#### Sublocations
+
+If the current stock location has any sublocations, they are listed here. Select any of the displayed sublocations to navigate to the detail view.
+
+### Stock Tab
+
+The *Stock* tab displays all the stock items available in this location. Tap a displayed stock item to navigate to the stock item detail view.
+
+{% with id="loc-stock", url="location_stock.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+
+The list of available stock items can be filtered using the input box at the top of the screen:
+
+{% with id="loc-filter", url="location_stock_filter.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+
+### Context Actions
+
+The following *Context Actions* are available for the selected location:
+
+{% with id="loc-actions", url="location_actions.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+
+#### New Location
+
+Create a new location under the current location:
+
+{% with id="loc-new", url="new_location.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+
+#### New Stock Item
+
+Create a new stock item in the current location:
+
+{% with id="loc-new-stock", url="new_stock_item_from_location.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+
+#### Scan Stock Items Into Location
+
+Use the barcode scanner to scan a stock item into the current location.
+
+
+## Stock Item Detail View
+
+The *Stock Item Detail* view displays information about a single stock item:
+
+{% with id="stock-detail", url="stock_detail.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+
+### Details Tab
+
+The *details* tab shows information about the selected stock item. Some of the displayed tiles provide further information when selected:
+
+#### Part Tile
+
+Part information is displayed at the top of the screen. Tap on this tile to navigate to the detail view for the linked part
+
+#### Location
+
+Tap on the location tile to navigate to the location detail view
+
+#### Notes
+
+Tap on the notes tile to display and edit the notes for this stock item
+
+### Actions Tab
+
+The *actions* tab displays the available actions for the selected stock item:
+
+{% with id="stock-actions", url="stock_actions.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Count Stock
+
+Select the *Count Stock* action to validate the current number of items in stock. Use this option to perform a quick stocktake!
+
+{% with id="stock-count", url="stock_count.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+!!! info "Serialized Stock"
+    The *count stock* action is not available for serialized stock items, as they have a fixed quantity of 1
+
+#### Remove Stock
+
+Select this action to remove a certain quantity from the selected stock item. For example, if there are 12 items available, and you take 3 items, the listed quantity will be reduced to 9 itemes.
+
+{% with id="stock-remove", url="stock_remove.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Add Stock
+
+Select this action to add a certain quantity to the selected stock item. For example, if there are 12 items available, and you add 3 items, the listed quantity will be increased to 15 items.
+
+{% with id="stock-add", url="stock_add.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Transfer Stock
+
+Transfer (move) the stock item to a new location:
+
+{% with id="stock-transfer", url="stock_transfer.png" %}
+{% include "app_img.html" %}
+{% endwith %}
+
+#### Scan Into Location
+
+Transfer the stock item into a new location by scanning the barcode for that location. If a *valid* stock location barcode is scanned, the stock item will be automatically relocated to that location
+
+#### Assign Barcode
+
+If a stock item has a third-party barcode (i.e. it has been received from a supplier with a barcode already printed) then this barcode can be used to track the stock item in InvenTree.
+
+Select the *assign barcode* action to scan this third-party barcode and assign it to this stock item.
+
+This barcode can then be used to track the stock item.
+
+#### Print Label
+
+If the server supports [label printing plugins](../extend/plugins/label.md), then an option to print a label for the selected stock item:
+
+{% with id="label_print_1", url="stock_print_label_1.png", description="Print label via plugin" %}
+{% include 'app_img.html' %}
+{% endwith %}
+
+{% with id="label_print_2", url="stock_print_label_2.png", description="Print label via plugin" %}
+{% include 'app_img.html' %}
+{% endwith %}
+
+### Edit Stock Item
+
+To edit the stock item details, select the *Edit* button in the top right corner of the screen:
+
+{% with id="stock-edit", url="stock_edit.jpg" %}
+{% include "app_img.html" %}
+{% endwith %}

docs/docs/app/translation.md

@@ -0,0 +1,15 @@
+---
+title: App Translations
+---
+
+## Translation Support
+
+The InvenTree app is designed to support multiple language translations.
+
+As with the web application, translations are community contributed - if the app does not support your native language, contributions are very welcome!
+
+## Contributing
+
+Translation for the InvenTree mobile app is provided by the [crowdin](https://crowdin.com/project/inventree) service. Contributions are welcomed and encouraged, and the process of providing or improving translated strings is extremely simple!
+
+Full translation efforts, while appreciated, are not required. Please feel free to contribute as much as you can!