Adds framework for documentation of user and global settings

docs/settings/SSO.md

@@ -0,0 +1,26 @@
+---
+title: InvenTree Single Sign On
+---
+
+## Single Sign On
+
+InvenTree provides the possibility to use 3rd party services to authenticate users. This functionality makes use of [django-allauth](https://django-allauth.readthedocs.io/en/latest/) and supports a wide array of OpenID and OAuth [provider](https://django-allauth.readthedocs.io/en/latest/providers.html).
+
+### Configuration
+
+To use SSO you have to:
+
+1. Enable the required providers in the [config file](../start/config.md#Single-Sign-on).
+1. Add the required client configurations in the `SocialApp` app in the [admin interface](../settings/admin.md).
+1. Enable SSO for the users in the [global settings](../settings/global.md).
+
+### Security Consideration
+
+You should use SSL for your website if you want to use this feature. Also set your callback-endpoints to `https://` addresses to reduce the risk of leaking user's tokens.
+
+Tokens for authenticating the users to the providers they registered with are saved in the database.  
+So ensure your database is protected and not open to the internet.  
+Make sure all users with admin privileges have sufficient passwords - they can read out your client configurations with providers and all auth-tokens from users.
+
+!!! warning "It's a secret!"
+    Never share your installs secret key!

docs/settings/admin.md

@@ -0,0 +1,56 @@
+---
+title: InvenTree Admin Interface
+---
+
+## Admin Interface
+
+Users which have *staff* privileges have access to an Admin interface which provides extremely low level control of the database. Every item in the database is available and this interface provides a convenient option for directly viewing and modifying database objects.
+
+!!! 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](./permissions.md).
+
+### Access Admin Interface
+
+To access the admin interface, select the "Admin" option from the drop-down user menu in the top-right corner of the screen.
+
+
+!!! info "Staff Only"
+    Only users with staff acccess will be able to see the "Admin" option
+
+An adminstation panel will be presented as shown below:
+
+{% with id="admin", url="admin/admin.png", description="InvenTree Admin Panel" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! info "Admin URL"
+    To directly access the admin iterface, append /admin/ to the InvenTree site URL - e.g. http://localhost:8000/admin/
+
+### View Database Objects
+
+Database objects can be listed and filtered directly. The image below shows an example of displaying existing part categories.
+
+{% with id="part_cats", url="admin/part_cats.png", description="Display part categories" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! info "Permissions"
+    A "staff" account does not necessarily provide access to all administration options, depending on the roles assigned to the user.
+
+#### Filtering
+
+Some admin views support filtering of results against specified criteria. For example, the list of Part objects can be filtered as follows:
+
+{% with id="filter", url="admin/filter.png", description="Filter part list" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Edit Database Objects
+
+Individual database objects can be edited directly in the admin interface. The image below shows an exmple of editing a Part object:
+
+{% with id="edit_part", url="admin/edit_part.png", description="Edit Part object" %}
+{% include 'img.html' %}
+{% endwith %}

docs/settings/email.md

@@ -0,0 +1,13 @@
+---
+title: Email Configured
+---
+
+## Email Settings
+
+InvenTree can be configured to send emails to users, for various purposes.
+
+To enable this, email configuration settings must be supplied to the InvenTree [configuration options](../start/config.md#email-settings).
+
+!!! info "Password Reset"
+    The *Password Reset* functionality requires the email backend to be correctly configured.
+

docs/settings/export.md

@@ -0,0 +1,17 @@
+---
+title: Exporting Data
+---
+
+## Exporting Data
+
+The Admin Interface 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' %}
+{% endwith %}
+
+Multiple data formats are supported for exported data:
+
+{% with id="formats", url="admin/formats.png", description="Data formats" %}
+{% include 'img.html' %}
+{% endwith %}

docs/settings/global.md

@@ -0,0 +1,70 @@
+---
+title: Global Settings
+---
+
+## Global Settings
+
+InvenTree ships with a lot of dynamic settings which can be configured at run-time. These settings are stored in the InvenTree database itself.
+
+The following settings are *global* settings which affect all users. 
+
+!!! info "Staff Status Required"
+    Only users with *staff* status can view and edit global settings
+
+To edit global settings, select *Settings* from the menu in the top-right corner of the screen.
+
+Global settings are arranged in the following categories:
+
+### Server Settings
+
+Configuration of basic server settings
+
+### Login Settings
+
+Change how logins, password-forgot, signups are handled.
+
+| Setting | Type | Description | Default |
+| --- | --- | --- | --- |
+| Enable registration | Boolean | Enable self-registration for users on the login-pages | False |
+| Enable SSO | Boolean | Enable SSO on the login-pages | False |
+| Enable password forgot | Boolean | Enable password forgot function on the login-pages.<br><br>This will let users reset their passwords on their own. For this feature to work you need to configure E-mail | True |
+| E-Mail required | Boolean | Require user to supply e-mail on signup.<br><br>Without a way (e-mail) to contact the user notifications and security features might not work! | False |
+| Mail twice | Boolean | On signup ask users twice for their mail | False |
+| Password twice | Boolean | On signup ask users twice for their password | True |
+| Auto-fill SSO users | Boolean | Automatically fill out user-details from SSO account-data.<br><br>If this feature is enabled the user is only asked for their username, first- and surname if those values can not be gathered from their SSO profile. This might lead to unwanted usernames bleading over. | True |
+
+### Barcodes
+
+Configuration of barcode functionality
+
+### Currencies
+
+Configuration of currency support
+
+### Reporting
+
+Configuration of report generation
+
+### Parts
+
+Configuration of Part options
+
+### Categories
+
+Configuration of Part Category options
+
+### Stock
+
+Configuration of Stock Item options
+
+### Build Orders
+
+Options for build orders
+
+### Purchase Orders
+
+Options for purchase orders
+
+### Sales orders
+
+Options for sales orders

docs/settings/import.md

@@ -0,0 +1,91 @@
+---
+title: Importing Data
+---
+
+## Importing Data
+
+External data can be imported via the admin interface, allowing for rapid integration of existing datasets, or bulk editing of table data.
+
+!!! danger "Danger"
+    Uploading bulk data directly is a non-reversible action.
+
+!!! warning "Backup"
+    Ensure you have made a backup of your database before performing bulk data import.
+
+!!! warning "Supported Models"
+    Not all models in the InvenTree database support bulk import actions.
+
+When viewing a model (which supports bulk data import) in the admin interface, select the "Import" button in the top-right corner:
+
+{% with id="import", url="admin/import.png", description="Data import" %}
+{% include 'img.html' %}
+{% endwith %}
+
+The next screen displays a list of column headings which are expected to be present in the uploaded data file.
+
+{% with id="import_upload", url="admin/import_upload.png", description="Data upload" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Select the data file to import, and the data format. Press the "Submit" button to upload the file.
+
+### File Format
+
+The uploaded data file must meet a number of formatting requirements for successful data upload. A simple way of ensuring that the file format is correct is to first [export data](./export.md) for the model in question, and delete all data rows (not the header row) from the exported data file.
+
+Then, the same file can be used as a template for uploading more data to the server.
+
+### ID Field
+
+The uploaded data file requires a special field called `id`. This `id` field uniquely identifies each entry in the database table(s) - it is also known as a *primary key*.
+
+The `id` column **must** be present in an uploaded data file, as it is required to know how to process the incoming data.
+
+Depending on the value of the `id` field in each row, InvenTree will attempt to either insert a new record into the database, or update an existing one.
+
+#### Empty ID
+
+If the `id` field in a given data row is empty (blank), then InvenTree interprets that particular row as a *new* entry which will be inserted into the database.
+
+If you wish for a new database entry to be created for a particular data row, the `id` field **must** be left blank for that row.
+
+#### Non-Empty ID
+
+If the `id` field in a given data row is *not* empty, then InvenTree inteprets that particular row as an *existing* row to override / update.
+
+In this case, InvenTree will search the database for an entry with the matching `id`. If a matching entry is found, then the entry is updated with the provided data.
+
+However, if an entry is *not* found with the matching `id`, InvenTree will return an error message, as it cannot find the matching database entry to update.
+
+!!! warning "Check id Value"
+    Exercise caution when uploading data with the `id` field specified!   
+
+### Import Preview
+
+After the data file has been uploaded and validated, the user is presented with a *preview* screen, showing the records that will be inserted or updated in the database.
+
+Here the user has a final chance to review the data upload.
+
+Press the *Confirm Import* button to actually perform the import process and commit the data into the database.
+
+{% with id="import_preview", url="admin/import_preview.png", description="Data upload preview" %}
+{% include 'img.html' %}
+{% endwith %}
+
+Note that *new* records are automatically assigned an `id` value.
+
+## Import Errors
+
+Manually importing data in a relational database is a complex process. You may be presented with an error message which describes why the data could not be imported.
+
+The error message should contain enough information to manually edit the data file to fix the problem.
+
+Any error messages are displayed per row, and you can hover the mouse over the particular error message to view specific error details:
+
+{% with id="import_error", url="admin/import_error.png", description="Data upload error" %}
+{% include 'img.html' %}
+{% endwith %}
+
+
+!!! info "Report Issue"
+    If the error message does not provide enough information, or the error seems like a bug caused by InvenTree itself, report an [issue on Github](https://github.com/inventree/inventree/issues).

docs/settings/logs.md

@@ -0,0 +1,29 @@
+---
+title: Admin Shell
+---
+
+## Error Logs
+
+Any critical server error logs are recorded to the database, and can be viewed by staff users using the admin interface.
+
+In the admin interface, select the "Errors" view:
+
+{% with id="admin_error_link", url="admin/admin_errors_link.png", description="Admin errors" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! info "URL"
+    Alternatively, navigate to the error list view at /admin/error_report/error/
+
+A list of error logs is presented.
+
+{% with id="admin_error_logs", url="admin/admin_errors.png", description="Error logs" %}
+{% include 'img.html' %}
+{% endwith %}
+
+!!! info "Deleting Logs"
+    Error logs should be deleted periodically
+
+## Reporting Errors
+
+Errors should be reported to the [InvenTree GitHub page](https://github.com/inventree/inventree/issues), and include the full error output as recorded to the error log.

docs/settings/permissions.md

@@ -0,0 +1,64 @@
+---
+title: User Permissions
+---
+
+## Permissions
+
+InvenTree provides access control to various features and data, by assigning each *user* to one (or more) *groups* which have multiple *roles* assigned.
+
+!!! info "Superuser"
+    The superuser account is afforded *all* permissions across an InvenTree intallation. This includes the admin interface, web interface, and API.
+
+### User
+
+A *user* is a single unique account with login credentials. By default, a user is not afforded *any* permissions, and the user must be assigned to the relevent group for the permissions to be assigned.
+
+### Group
+
+A *group* is a named set of zero or more users. Each group is assigned permissions against each possible role.
+
+### Role
+
+A *role* is a set of distinct permissions linked to a given subset of InvenTree functionality (more on this below).
+
+## Roles
+
+InvenTree functionality is split into a number of distinct roles. A group will have a set of permissions assigned to each of the following roles:
+
+- **Admin** - The *admin* role is related to assigning user permissions.
+- **Part Category** - The *part category* role is related to accessing Part Category data
+- **Part** - The *part* role is related to accessing Part data
+- **Stock Location** - The *stock location* role is related to accessing Stock Location data
+- **Stock Item** - The *stock item* role is related to accessing Stock Item data
+- **Build** - The *build* role is related to accessing Build Order and Bill of Materials data
+- **Purchase** - The *purchase* role is related to accessing Purchase Order data
+- **Sales** - The *sales* role is related to accessing Sales Order data
+
+{% with id="Roles Admin View", url="admin/roles.png", description="Roles" %}
+{% include 'img.html' %}
+{% endwith %}
+
+### Role Permissions
+
+Within each role, there are four levels of available permissions:
+
+- **View** - The *view* permission allows viewing of content related to the particular role
+- **Change** - The *change* permission allows the user to edit / alter / change data associated with the particular role
+- **Add** - The *add* permission allows the user to add / create database records associated with the particular role
+- **Delete** - The *delete* permission allows the user to delete / remove database records associated with the particular role
+
+## Admin Interface Permissions
+
+If a user does not have the required permissions to perform a certain action in the admin interface, those options not be displayed.
+
+If a user is expecting a certain option to be available in the admin interface, but it is not present, it is most likely the case that the user does not have those permissions assigned. 
+
+## Web Interface Permissions
+
+When using the InvenTree web interface, certain functions may not be available for a given user, depending on their permissions. In this case, user-interface elements may be disabled, or may be removed.
+
+## API Permissions
+
+When using the InvenTree API, certain endpoints or actions may be inaccessible for a given user, depending on their permissions.
+
+As the API is used extensively within the web interface, this means that many data tables may also be impacted by user permissions.

docs/settings/shell.md

@@ -0,0 +1,24 @@
+---
+title: Admin Shell
+---
+
+## Python Shell
+
+A Python shell interface is provided at the URL `/admin/shell/`.
+
+This interface allows advanced users direct access to the underlying database objects using Python. 
+
+!!! warning "Danger"
+    The scripting shell interface should only ever be used by advanced users. It requires intimate knowledge of the underlying InvenTree code, and improper use could easily result in corruption of data
+
+!!! warning "Seriously"
+    If you are not 100% sure of what you are doing, do not use the shell interface
+
+!!! info "Enabling Shell Mode"
+    The admin shell is (by default) only enabled when InvenTree is running in DEBUG mode
+
+The shell interface allows Python queries to be run by the admin user, as shown below:
+
+{% with id="admin_shell", url="admin/shell.png", description="Admin shell interface" %}
+{% include 'img.html' %}
+{% endwith %}

docs/settings/tasks.md

@@ -0,0 +1,29 @@
+---
+title: Background Tasks
+---
+
+## Background Tasks
+
+In addition to managing the database and providing a web interface, InvenTree runs various background tasks;
+
+### Blocking Operations
+
+Some tasks (such as sending emails or performing bulk database actions) may take a significant amount of time. Instead of delaying the response to the user, these tasks are handled by the background task manager.
+
+### Periodic Tasks
+
+Some tasks must be performed on a regular, periodic basis. 
+
+## Django Q 
+
+InvenTree uses the [django-q](https://django-q.readthedocs.io/en/latest/) background task manager.
+
+### Running Worker
+
+The Django Q work must run separately to the web server. This is started as a separate process, as part of the InvenTree installation instructions.
+
+If the worker is not running, a warning indicator is displayed in the InvenTree menu bar.
+
+## Admin Interface
+
+Scheduled tasks can be viewed in the InvenTree admin interface.

docs/settings/user.md

@@ -0,0 +1,33 @@
+---
+title: User Settings
+---
+
+## User Settings
+
+The various user settings described below can be configured for an individual user, to provide an InvenTree user experienced customized to their preferences.
+
+User settings are arranged in the following categories:
+
+### Account
+
+User account configuration
+
+### Home Page
+
+Customize display of items on the InvenTree home page
+
+### Search
+
+Customize settings for search results
+
+### Labels
+
+Settings for label printing
+
+### Reports
+
+Settings for report generation
+
+### Forms
+
+Customize behavior of modal forms