Mirrored_Repos/InvenTree
1
0
Fork 0
mirror of https://github.com/inventree/InvenTree synced 2024-08-30 18:33:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #737 from SchrodingersGat/doc-updates

Browse Source 
Remove some docs pages
This commit is contained in:
Oliver 2020-04-18 14:55:04 +10:00 committed by GitHub
commit 9cb1af9587
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 10 additions and 365 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@ -9,18 +9,18 @@ InvenTree is designed to be lightweight and easy to use for SME or hobbyist appl
However, powerful business logic works in the background to ensure that stock tracking history is maintained, and users have ready access to stock level information. However, powerful business logic works in the background to ensure that stock tracking history is maintained, and users have ready access to stock level information.
## User Documentation ## Getting Started
For InvenTree documentation, refer to the [user documentation](https://inventree.github.io). Refer to the [getting started guide](https://inventree.github.io/docs/start/install) for installation and setup instructions.
## Documentation
For InvenTree documentation, refer to the [InvenTre documentation website](https://inventree.github.io).
## Developer Documentation ## Developer Documentation
For site administrator and project code documentation, refer to the [developer documentation](http://inventree.readthedocs.io/en/latest/). This includes auto-generated documentation of the InvenTree python codebase. For code documentation, refer to the [developer documentation](http://inventree.readthedocs.io/en/latest/).
## Getting Started ## Contributing
Refer to the [getting started guide](https://inventree.readthedocs.io/en/latest/start.html) for installation and setup instructions. Contributions are welcomed and encouraged. Please help to make this project even better! Refer to the [contribution page](https://inventree.github.io/pages/contribute).
## Third Party Extensions
[InvenTree Docker](https://github.com/Zeigren/inventree-docker) - A docker build for InvenTree by [Zeigren](https://github.com/Zeigren)

14
docs/backup.rst
View File

@ -1,14 +0,0 @@
Backup and Restore
==================
.. toctree::
:titlesonly:
:maxdepth: 2
:caption: Backup
:hidden:
InvenTree provides database backup and restore functionality through the `django-dbbackup <https://github.com/django-dbbackup/django-dbbackup>`_ extension.
This extension allows database models and uploaded media files to be backed up (and restored) via the command line.
In the root InvenTre directory, run ``make backup`` to generate backup files for the database models and media files.

79
docs/config.rst
View File

@ -1,79 +0,0 @@
InvenTree Configuration
=======================
.. toctree::
:titlesonly:
:maxdepth: 2
:caption: Configuration
:hidden:
Admin users will need to adjust the InvenTree installation to meet the particular needs of their setup. For example, pointing to the correct database backend, or specifying a list of allowed hosts.
The Django configuration parameters are found in the normal place (*settings.py*). However the settings presented in this file should not be adjusted as they will alter the core behaviour of the InvenTree application.
To support install specific settings, a simple configuration file ``config.yaml`` is provided. This configuration file is loaded by **settings.py** at runtime. Settings specific to a given install should be adjusted in ``config.yaml``.
The default configuration file launches a *DEBUG* configuration with a simple SQLITE database backend. This default configuration file is shown below:
.. literalinclude :: ../InvenTree/config_template.yaml
:language: yaml
:linenos:
Database Options
----------------
InvenTree provides support for multiple database backends - any backend supported natively by Django can be used.
Database options are specified under the *database* heading in the configuration file. Any option available in the Django documentation can be used here - it is passed through transparently to the management scripts.
**SQLite:**
By default, InvenTree uses an sqlite database file : ``inventree_db.sqlite3``. This provides a simple, portable database file that is easy to use for debug and testing purposes.
**MySQL:** MySQL database backend is supported with the native Django implemetation. To run InvenTree with the MySQL backend, a number of extra packages need to be installed:
* mysql-server - *MySQL backend server*
* libmysqlclient-dev - *Required for connecting to the MySQL database in Python*
* (pip) mysqlclient - *Python package for communication with MySQL database*
These requirements can be installed from the base directory with the command ``make mysql``.
It is then up to the database adminstrator to create a new MySQL database to store inventree data, in addition to a username/password to access the data.
.. important:: MySQL Collation:
When creating the MySQL database, the adminstrator must ensure that the collation option is set to *utf8_unicode_520_ci* to ensure that InvenTree features function correctly.
The database options (in the ``config.yaml`` file) then need to be adjusted to communicate the MySQL backend. Refer to the `Django docs <https://docs.djangoproject.com/en/dev/ref/databases/>`_ for further information.
**PostgreSQL:** PostgreSQL database backend is supported with the native Django implementation. Note that to use this backend, the following system packages must be installed:
* postgresql
* postgresql-contrib
* libpq-dev
* (pip3) psycopg2
These requirements can be installed from the base directory with the command ``make postgresql``.
It is then up to the database adminstrator to create a new PostgreSQL database to store inventree data, in addition to a username/password to access the data.
The database options (in the ``config.yaml`` file) then need to be adjusted to communicate the PostgreSQL backend. Refer to the `Django docs <https://docs.djangoproject.com/en/dev/ref/databases/>`_ for further information.
Allowed Hosts / CORS
--------------------
By default, all hosts are allowed, and CORS requests are enabled from any origin. **This is not secure and should be adjusted for your installation**. These options can be changed in the configuration file.
For further information, refer to the following documentation:
* `Django ALLOWED_HOSTS <https://docs.djangoproject.com/en/2.2/ref/settings/#allowed-hosts>`_
* `Django CORS headers <https://github.com/OttoYiu/django-cors-headers>`_
Uploaded File Storage
---------------------
By default, uploaded files are stored in the local direction ``./media``. This directory should be changed based on the particular installation requirements.
Backup Location
---------------
The default behaviour of the database backup is to generate backup files for database tables and media files to the user's temporary directory. The target directory can be overridden by setting the *backup_dir* parameter in the config file.

54
docs/deploy.rst
View File

@ -1,54 +0,0 @@
Deploying InvenTree
===================
.. toctree::
:titlesonly:
:maxdepth: 2
:caption: Deployment
:hidden:
The development server provided by the Django ecosystem may be fine for a testing environment or small contained setups. However special consideration must be given when deploying InvenTree in a real-world environment.
Django apps provide multiple deployment methods - see the `Django documentation <https://docs.djangoproject.com/en/2.2/howto/deployment/>`_.
There are also numerous online tutorials describing how to deploy a Django application either locally or on an online platform.
Following is a simple tutorial on serving InvenTree using `Gunicorn <https://gunicorn.org/>`_. Gunicorn is a Python WSGI server which provides a multi-worker server which is much better suited to handling multiple simultaneous requests.
Install Gunicorn
----------------
Gunicorn can be installed using PIP:
``pip3 install gunicorn``
Configure Static Directories
----------------------------
Directories for storing *media* files and *static* files should be specified in the ``config.yaml`` configuration file. These directories are the ``MEDIA_ROOT`` and ``STATIC_ROOT`` paths required by the Django app.
Collect Static Files
--------------------
The required static files must be collected into the specified ``STATIC_ROOT`` directory:
``python3 InvenTree/manage.py collectstatic``
Configure Gunicorn
------------------
The Gunicorn server can be configured with a simple configuration file (e.g. python script). An example configuration file is provided in ``InvenTree/gunicorn.conf.py``
.. literalinclude :: ../InvenTree/gunicorn.conf.py
:language: python
:linenos:
This file can be used to configure the Gunicorn server to match particular requirements.
Run Gunicorn
------------
From the directory where ``manage.py`` is located:
Run ``gunicorn -c gunicorn.conf.py InvenTree.wsgi``

6
docs/index.rst
View File

@ -7,13 +7,7 @@ InvenTree Source Documentation
:caption: Index :caption: Index
:hidden: :hidden:
Getting Started<start>
Configuration<config>
Deployment<deploy>
Migrate Data<migrate>
Update InvenTree<update>
Translations<translate> Translations<translate>
Backup and Restore<backup>
Modal Forms<forms> Modal Forms<forms>
Tables<tables> Tables<tables>
REST API<rest> REST API<rest>

36
docs/migrate.rst
View File

@ -1,36 +0,0 @@
Migrating Data
==============
.. toctree::
:titlesonly:
:maxdepth: 2
:caption: Migrating Data
:hidden:
In the case that data needs to be migrated from one database installation to another, the following procedure can be used to export data, initialize the new database, and re-import the data.
Export Data
-----------
``python3 InvenTree/manage.py dumpdata --exclude contenttypes --exclude auth.permission --indent 2 > data.json``
This will export all data (including user information) to a json data file.
Initialize Database
-------------------
Configure the new database using the normal processes (see `Getting Started <start.html>`_):
``python3 InvenTree/manage.py makemigrations``
``python3 InvenTree/manage.py migrate --run-syncdb``
Import Data
-----------
The new database should now be correctly initialized with the correct table structures requried to import the data.
``python3 InvenTree/manage.py loaddata data.json``
.. important::
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 data file may be required.

124
docs/start.rst
View File

@ -1,124 +0,0 @@
Getting Started Guide
=====================
.. toctree::
:titlesonly:
:maxdepth: 2
:caption: Getting Started
:hidden:
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.
A makefile in the root directory provides shortcuts for the installation process, and can also be very useful during development.
Requirements
------------
To install InvenTree you will need the following system components installed:
* python3
* python3-dev
* python3-pip (pip3)
* g++
* make
Each of these programs need to be installed (e.g. using apt or similar) before running the ``make install`` script:
```
sudo apt-get install python3 python3-dev python3-pip g++ make
```
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.
To configure Inventree inside a virtual environment, ``cd`` into the inventree base directory and run the following commands:
``apt-get install python3-venv``
``python3 -m venv inventree-env``
``source inventree-env/bin/activate``
This will place the current shell session inside a virtual environment - the terminal should display the ``(inventree-env)`` prefix.
.. note::
Remember to run ``source inventree-env/bin/activate`` when starting each shell session, before running Inventree commands. This will ensure that the correct environment is being used.
Installation
------------
First, download the latest InvenTree source code:
``git clone https://github.com/inventree/inventree/``
InvenTree is a Python/Django application and relies on the pip package manager. All packages required to develop and test InvenTree can be installed via pip. Package requirements can be found in ``requirements.txt``.
To setup the InvenTree environment, *cd into the inventree directory* and run the command:
``make install``
which installs all required Python packages using pip package manager. It also creates a (default) database configuration file which needs to be edited to meet user needs before proceeding (see next step below).
Additionally, this step creates a *SECRET_KEY* file which is used for the django authentication framework.
.. important::
The *SECRET_KEY* file should never be shared or made public.
Database Configuration
-----------------------
Once the required packages are installed, the database configuration must be adjusted to suit your particular needs. InvenTree provides a simple default setup which should work *out of the box* for testing and debug purposes.
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 <config.html>`_ section.
Initialize Database
-------------------
Once install settings are correctly configured (in *config.yaml*) run the initial setup script:
``make migrate``
This performs the initial database migrations, creating the required tables, etc.
The database should now be installed!
Create Admin Account
--------------------
Create an initial superuser (administrator) account for the InvenTree instance:
``make superuser``
Run Development Server
----------------------
Run ``cd InvenTree && python3 manage.py runserver 127.0.0.1:8000`` to launch a development server. This will launch the InvenTree web interface at ``127.0.0.1:8000``. For other options refer to the `django docs <https://docs.djangoproject.com/en/2.2/ref/django-admin/>`_.
Database Migrations
-------------------
Whenever a change is made to the underlying database schema, database migrations must be performed. Call ``make migrate`` to run any outstanding database migrations.
Development and Testing
-----------------------
Other shorthand functions are provided for the development and testing process:
* ``make install`` - Install all required underlying packages using PIP
* ``make update`` - Update InvenTree installation (after database configuration)
* ``make superuser`` - Create a superuser account
* ``make migrate`` - Perform database migrations
* ``make mysql`` - Install packages required for MySQL database backend
* ``make postgresql`` - Install packages required for PostgreSQL database backend
* ``make translate`` - Compile language translation files (requires gettext system package)
* ``make backup`` - Backup database tables and media files
* ``make test`` - Run all unit tests
* ``make coverage`` - Run all unit tests and generate code coverage report
* ``make style`` - Check Python codebase against PEP coding standards (using Flake)
* ``make docreqs`` - Install the packages required to generate documentation
* ``make docs`` - Generate this documentation

42
docs/update.rst
View File

@ -1,42 +0,0 @@
Update InvenTree
================
.. toctree::
:titlesonly:
:maxdepth: 2
:caption: Update
:hidden:
Adminitrators wishing to update InvenTree to the latest version should follow the instructions below. The commands listed below should be run from the InvenTree root directory.
.. important::
It is advisable to backup the InvenTree database before performing these steps. The particular backup procedure may depend on your installation details. To perform a simple database dump, run the command ``make backup``.
Stop Server
-----------
Stop the InvenTree server (e.g. gunicorn)
Update Source
-------------
Update the InvenTree source code to the latest version.
``git pull origin master``
Perform Migrations
------------------
Updating the database is as simple as calling the makefile target:
``make update``
This command performs the following steps:
* Perform required database schema changes
* Collect required static files
Restart Server
--------------
Restart the InvenTree server