diff --git a/docs/_static/img/api_doc.png b/docs/_static/img/api_doc.png new file mode 100644 index 0000000000..1466eb7b54 Binary files /dev/null and b/docs/_static/img/api_doc.png differ diff --git a/docs/_static/img/api_http.png b/docs/_static/img/api_http.png new file mode 100644 index 0000000000..59f7dfa112 Binary files /dev/null and b/docs/_static/img/api_http.png differ diff --git a/docs/_static/img/modal_form.png b/docs/_static/img/modal_form.png new file mode 100644 index 0000000000..a1daf28e21 Binary files /dev/null and b/docs/_static/img/modal_form.png differ diff --git a/docs/backup.rst b/docs/backup.rst new file mode 100644 index 0000000000..6e36a65a1a --- /dev/null +++ b/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 `_ extension. + +This extension allows databas models and uploaded media files to be backed up (and restored) via the command line. \ No newline at end of file diff --git a/docs/forms.rst b/docs/forms.rst new file mode 100644 index 0000000000..a30253d51d --- /dev/null +++ b/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 `_ 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 `_ 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 diff --git a/docs/index.rst b/docs/index.rst index 47c0b88b5e..34ebc992b0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,12 +1,39 @@ -InvenTree's Django Documentation +InvenTree Source Documentation ================================ -This documentation is auto-generated from the `InvenTree codebase `_ - .. toctree:: :titlesonly: :maxdepth: 2 - :caption: Contents: + :caption: Index + :hidden: - InvenTree Modules - API Reference \ No newline at end of file + Getting Started + Modal Forms + Tables + REST API + Backup and Restore + InvenTree Modules + Module 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 `_. + +Documentation for the Python modules is auto-generated from the `InvenTree codebase `_. + +Code Structure +-------------- + +**Backend** + +InvenTree is developed using the `django web framework `_, 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 `_ 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. \ No newline at end of file diff --git a/docs/introduction.rst b/docs/introduction.rst deleted file mode 100644 index f33917212a..0000000000 --- a/docs/introduction.rst +++ /dev/null @@ -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 `_ - High level management functions -* `Build `_ - Part build projects -* `Company `_ - Company management (suppliers / customers) -* `Part `_ - Part management -* `Stock `_ - Stock management \ No newline at end of file diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000000..183e49bfe4 --- /dev/null +++ b/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 `_ - High level management functions +* `Build `_ - Part build projects +* `Company `_ - Company management (suppliers / customers) +* `Part `_ - Part management +* `Stock `_ - Stock management \ No newline at end of file diff --git a/docs/reference.rst b/docs/reference.rst index de81c25e26..bbf9958fcb 100644 --- a/docs/reference.rst +++ b/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` diff --git a/docs/rest.rst b/docs/rest.rst new file mode 100644 index 0000000000..73dd8d0e87 --- /dev/null +++ b/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) `_ 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``. diff --git a/docs/start.rst b/docs/start.rst new file mode 100644 index 0000000000..5bc50d0f88 --- /dev/null +++ b/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 `_. + +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 \ No newline at end of file diff --git a/docs/tables.rst b/docs/tables.rst new file mode 100644 index 0000000000..58f6aefb48 --- /dev/null +++ b/docs/tables.rst @@ -0,0 +1,14 @@ +Table Management +================ + +.. toctree:: + :titlesonly: + :maxdepth: 2 + :caption: Tables + :hidden: + +InvenTree uses `Bootstrap Table `_ 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``. \ No newline at end of file