Merge pull request #232 from SchrodingersGat/docs

Added a bunch of developer documentation

docs/backup.rst

@@ -0,0 +1,12 @@
+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 databas models and uploaded media files to be backed up (and restored) via the command line.

docs/forms.rst

@@ -0,0 +1,57 @@
+InvenTree Modal Forms
+=====================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+   :caption: Modal Forms
+   :hidden:
+
+
+The InvenTree web interface uses modal forms for user input. InvenTree defines a wrapper layer around the Django form classes to provide a mechanism for retrieving and rendering forms via jQuery and AJAX.
+
+.. image:: _static/img/modal_form.png
+
+Forms are rendered to a Bootstrap modal window, allowing in-page data input and live page updating.
+
+Crispy Forms
+------------
+
+Django provides native form rendering tools which are very powerful, allowing form rendering, input validation, and display of error messages for each field.
+
+InvenTree makes use of the `django-crispy-forms <https://github.com/django-crispy-forms/django-crispy-forms>`_ extension to reduce the amount of boilerplate required to convert a Django model to a HTML form.
+
+Form Rendering
+--------------
+
+The InvenTree front-end web interface is implemented using jQuery and Bootstrap. Forms are rendered using Django `class-based forms <https://docs.djangoproject.com/en/2.2/topics/class-based-views/generic-editing/>`_ using standard Django methods. 
+
+The main point of difference is that instead of rendering a HTTP response (and displaying a static form page) form data are requested via AJAX, and the form contents are injected into the modal window.
+
+A set of javascript/jQuery functions handle the client/server interactions, and manage GET and POST requests.
+
+Sequence of Events
+------------------
+
+#. User presses a button or other element which initiates form loading
+#. jQuery function sends AJAX GET request to InvenTree server, requesting form at a specified URL
+#. Django renders form (according to specific model/view rules)
+#. Django returns rendered form as a JSON object
+#. Client displays the modal window and injects the form contents into the modal
+#. User fills in form data, presses the 'Submit' button
+#. Client sends the completed form to server via POST
+#. Django backend handles POST request, specifically determines if the form is valid
+#. Return a JSON object containing status of form validity
+  * If the form is valid, return (at minimum) {form_valid: true}. Client will close the modal.
+  * If the form is invalid, re-render the form and send back to the client. Process repeats
+
+At the end of this process (i.e. after successful processing of the form) the client closes the modal and runs any optional post-processes (depending on the implementation).
+
+Further Reading
+---------------
+
+For a better understanding of the modal form architecture, refer to the relevant source files:
+
+**Server Side:** Refer to ``./InvenTree/InvenTree/views.py`` for AJAXified Django Views
+
+**Client Side:** Refer to ``./InvenTree/static/script/inventree/modals.js`` for client-side javascript

docs/index.rst

@@ -1,12 +1,39 @@
-InvenTree's Django Documentation
+InvenTree Source Documentation
 ================================
 
-This documentation is auto-generated from the `InvenTree codebase <https://github.com/InvenTree/InvenTree>`_
-
 .. toctree::
    :titlesonly:
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Index
+   :hidden:
 
-   InvenTree Modules <introduction>
+   Getting Started<start>
-   API Reference<reference>
+   Modal Forms<forms>
+   Tables<tables>
+   REST API<rest>
+   Backup and Restore<backup>
+   InvenTree Modules <modules>
+   Module Reference<reference>
+
+The documentation found here is provided to be useful for developers working on the InvenTree codebase. User documentation can be found on the `InvenTree website <https://inventree.github.io>`_.
+
+Documentation for the Python modules is auto-generated from the `InvenTree codebase <https://github.com/InvenTree/InvenTree>`_.
+
+Code Structure
+--------------
+
+**Backend**
+
+InvenTree is developed using the `django web framework <https://www.djangoproject.com/>`_, a powerful toolkit for making web applications in Python.
+
+The database management code and business logic is written in Python 3. Core functionality is separated into individual modules (or *apps* using the django nomenclature).
+
+Each *app* is located in a separate directory under InvenTree. Each *app* contains python modules named according to the standard django configuration.
+
+**Frontend**
+
+The web frontend rendered using a mixture of technologies.
+
+Base HTML code is rendered using the `django templating language <https://docs.djangoproject.com/en/2.2/topics/templates/>`_ which provides low-level access to the underlying database models.
+
+jQuery is also used to implement front-end logic, and desponse to user input. A REST API is provided to facilitate client-server communication.

docs/introduction.rst

@@ -1,28 +0,0 @@
-InvenTree
-=========
-
-InvenTree is an open source inventory management system which provides powerful low-level part management and stock tracking functionality.
-
-The core of the InvenTree software is a Python/Django database backend whi
-
-
-**Django Apps**
-
-The InvenTree Django ecosystem provides the following 'apps' for core functionality:
-
-.. toctree::
-   :titlesonly:
-   :maxdepth: 1
-   :caption: App Modules:
-
-   docs/InvenTree/index
-   docs/build/index
-   docs/company/index
-   docs/part/index
-   docs/stock/index
-   
-* `InvenTree </docs/InvenTree/index.html>`_ - High level management functions
-* `Build </docs/build/index.html>`_ - Part build projects
-* `Company </docs/company/index.html>`_ - Company management (suppliers / customers)
-* `Part </docs/part/index.html>`_ - Part management
-* `Stock </docs/stock/index.html>`_ - Stock management 

docs/modules.rst

@@ -0,0 +1,22 @@
+InvenTree Modules
+=================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+   :caption: App Modules
+   :hidden:
+
+   docs/InvenTree/index
+   docs/build/index
+   docs/company/index
+   docs/part/index
+   docs/stock/index
+
+The InvenTree Django ecosystem provides the following 'apps' for core functionality:
+   
+* `InvenTree <docs/InvenTree/index.html>`_ - High level management functions
+* `Build <docs/build/index.html>`_ - Part build projects
+* `Company <docs/company/index.html>`_ - Company management (suppliers / customers)
+* `Part <docs/part/index.html>`_ - Part management
+* `Stock <docs/stock/index.html>`_ - Stock management 

docs/reference.rst

@@ -1,6 +1,13 @@
-API Reference Index
+Module Reference
 ===================
 
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+   :caption: Module Reference
+   :hidden:
+
+
 The complete reference indexes are found below:
 
 * :ref:`modindex`

docs/rest.rst

@@ -0,0 +1,37 @@
+REST API
+========
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+   :caption: REST API
+   :hidden:
+
+InvenTree provides a REST API which serves data to the web client and also provides data access to third-party applications. The REST API is implemented using the `Django REST framework (DRF) <https://www.django-rest-framework.org/>`_ which provides the following features out of the box:
+
+* AJAX REST API
+* Web-browseable REST
+* User authentication 
+* Database model serialization and validation
+
+API Access
+----------
+
+The API is accessible from the root URL ``/api/``. It requires user authentication.
+
+* Requesting data via AJAX query will return regular JSON objects. 
+* Directing a browser to the API endpoints provides a web-browsable interface
+
+.. image:: _static/img/api_http.png
+
+API Documentation
+-----------------
+
+API documentation is provided by DRF autodoc tools, and is available for browsing at ``/api-doc/``
+
+.. image:: _static/img/api_doc.png
+
+API Code
+--------
+
+Javascript/jQuery code for interacting with the server via the REST API can be found under ``InvenTree/static/script/InvenTree``.

docs/start.rst

@@ -0,0 +1,51 @@
+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 makefile in the root directory provides shortcuts for the installation process, and can also be very useful during development.
+
+Installation
+------------
+
+All packages required to develop and test InvenTree can be installed via pip package manager. Package requirements can be found in ``requirements.txt``.
+
+To setup the InvenTree environment, run the command
+
+``make install``
+
+which performs the following actions:
+
+* Installs all required Python packages using pip package manager
+* Generates a SECREY_KEY file required for the django authentication framework
+
+Superuser Account
+-----------------
+
+Run ``make supeuser`` to create a superuser account, required for initial system login.
+
+Run Development Server
+----------------------
+
+Run ``python InvenTree/manage.py runserver`` 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 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

docs/tables.rst

@@ -0,0 +1,14 @@
+Table Management
+================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+   :caption: Tables
+   :hidden:
+
+InvenTree uses `Bootstrap Table <https://bootstrap-table.com/>`_ to manage tabulated data in the web front-end. The ability to tabulate data from read via an AJAX request allows tables to be updated on-the-fly (without a full page reload).
+
+Bootstrap Table also provides integrated tools for table searching, filtering, and advanced rendering.
+
+Frontend code for table functionality can be found at ``InvenTree/static/script/inventree/tables.js``.