Merge pull request #456 from SchrodingersGat/install-docs

Improve installation documentation

.travis.yml

@@ -10,8 +10,7 @@ addons:
         -sqlite3
 
 before_install:
-    - make requirements
-    - make setup
+    - make install
     - make migrate
 
 script:

InvenTree/config_template.yaml

@@ -13,8 +13,8 @@ database:
   # Example Configuration - MySQL
   #ENGINE: django.db.backends.mysql
   #NAME: inventree
-  #USER: inventree
-  #PASSWORD: password
+  #USER: inventree_username
+  #PASSWORD: inventree_password
   #HOST: ''
   #PORT: ''
 
@@ -52,4 +52,5 @@ log_queries: False
 
 # Backup options
 # Set the backup_dir parameter to store backup files in a specific location
+# If unspecified, the local user's temp directory will be used
 #backup_dir: '/home/inventree/backup/'

Makefile

@@ -7,6 +7,7 @@ clean:
 	rm -rf .tox
 	rm -f .coverage
 
+# Perform database migrations (after schema changes are made)
 migrate:
 	python3 InvenTree/manage.py makemigrations company
 	python3 InvenTree/manage.py makemigrations part
@@ -16,40 +17,47 @@ migrate:
 	python3 InvenTree/manage.py migrate --run-syncdb
 	python3 InvenTree/manage.py check
 
-requirements:
+# Install all required packages
+install:
 	pip3 install -U -r requirements.txt
-
-setup:
 	python3 InvenTree/setup.py
 
+# Create a superuser account
 superuser:
 	python3 InvenTree/manage.py createsuperuser
 
-install: requirements setup migrate superuser
-
+# Install pre-requisites for mysql setup
 mysql:
 	apt-get install mysql-server
 	apt-get install libmysqlclient-dev
 	pip3 install mysqlclient
 
+# Run PEP style checks against source code
 style:
 	flake8 InvenTree
 
+# Run unit tests
 test:
 	python3 InvenTree/manage.py check
 	python3 InvenTree/manage.py test build company part stock order
 
+# Run code coverage
 coverage:
 	python3 InvenTree/manage.py check
 	coverage run InvenTree/manage.py test build company part stock order InvenTree
 	coverage html
 
-documentation:
+# Install packages required to generate code docs
+docreqs:
 	pip3 install -U -r docs/requirements.txt
-	cd docs & make html
 
+# Build code docs
+docs:
+	cd docs && make html
+
+# Make database backup
 backup:
 	python3 InvenTree/manage.py dbbackup
 	python3 InvenTree/manage.py mediabackup
 
-.PHONY: clean migrate requirements setup superuser install mysql style test coverage documentation backup
+.PHONY: clean migrate superuser install mysql style test coverage docreqs docs backup

docs/config.rst

@@ -41,7 +41,7 @@ These requirements can be installed from the base directory with the command ``m
 It is up to the database adminstrator to create a new database to store inventree data, in addition to a username/password to access the data.
 
 .. important:: MySQL Collation: 
-    When creating the database, the adminstrator must ensure that the collation option is set to *utf8_unicode_520_ci* to ensure that InvenTree features function correctly.
+    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 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.
 

docs/index.rst

@@ -14,6 +14,7 @@ InvenTree Source Documentation
    Tables<tables>
    REST API<rest>
    Backup and Restore<backup>
+   Migrate Data<migrate>
    InvenTree Modules <modules>
    Module Reference<reference>
 

docs/migrate.rst

@@ -0,0 +1,33 @@
+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 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 manage.py makemigrations``
+
+``python3 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 manage.py loaddata data.json``

docs/start.rst

@@ -11,31 +11,62 @@ To install a complete *development* environment for InvenTree, follow the steps
 
 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:
+
+* python3
+* pip3
+* make
+
 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, run the command:
+To setup the InvenTree environment, *cd into the inventree directory* and run the command:
 
 ``make install``
 
-which performs the following actions:
+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).
 
-* Installs all required Python packages using pip package manager
-* Generates a SECREY_KEY file required for the django authentication framework
-* Performs initial database installation and migrations
-* Prompts user to create a superuser account
+Additionally, this step creates a *SECREY_KEY* file which is used for the django authentication framework. 
 
-Install Configuration
----------------------
+.. important:: 
+    The *SECREY_KEY* file should never be shared or made public. 
 
-InvenTree provides a simple default setup which should work *out of the box* for testing and debug purposes. For installation in production environments, further configuration options are available in the ``config.yaml`` configuration file. 
+Database Configuration
+-----------------------
 
-The configuration file provides administrators control over various setup options without digging into the Django ``settings.py`` script. The default setup uses a sqlite database with *DEBUG* mode enabled.
+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``
+
+which 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
 ----------------------
 
@@ -58,4 +89,5 @@ Other shorthand functions are provided for the development and testing process:
 * ``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 documentation`` - Generate this documentation
+* ``make docreqs`` - Install the packages required to generate documentation
+* ``make docs`` - Generate this documentation