Merge pull request #599 from gurch101/update-getting-started-guides

Update "Getting Started" pages in documentation (SHUUP-2959)

doc/getting_started.rst

@@ -4,7 +4,13 @@ Getting Started with Shuup
 .. note::
 
    If you are planning on developing Shuup,
-   read the :doc:`other Getting Started guide <getting_started_dev>` instead.
+   read the :doc:`Getting Started with Shuup Development guide
+   <getting_started_dev>` instead.
+
+Requirements
+------------
+* Python 2.7.9+/3.4+. https://www.python.org/download/.
+* Any database supported by Django.
 
 Installation
 ------------
@@ -14,19 +20,52 @@ Installation
 This guide assumes familiarity with the PyPA tools for Python packaging,
 including ``pip`` and ``virtualenv``.
 
-1. Set up a new virtualenv for your Shuup project.
-2. Grab a Git clone of the Shuup sources. For this guide,
-   we'll assume the checkout of the clone lives in :file:`/stuff/shuup`.
-3. Activate the virtualenv. Within the virtualenv, run
+1. Update pip and setuptools
+
+   .. code-block:: shell
+
+      pip install -U pip
+      pip install -U setuptools
+
+2. Set up a new virtualenv for Shuup and activate it
+
+   .. code-block:: shell
+
+      virtualenv shuup-venv
+      . shuup-venv/bin/activate
+
+3. Download the latest Shuup Wheel package from
+   https://github.com/shuup/shuup/releases and run
 
    .. code-block:: shell
 
-      pip install /stuff/shuup
+      pip install /path/to/shuup/whl
+
+4. Once installed, you can begin setting up a Django project using whichever
+   standards you fancy. Refer to the top-level `settings
+   <https://github.com/shuup/shuup/blob/master/shuup_workbench/settings/base_settings.py>`_
+   and `urls
+   <https://github.com/shuup/shuup/blob/master/shuup_workbench/urls.py>`_
+   for configuration details. At minimum, you will need to add ``shuup.core``
+   to your ``INSTALLED_APPS``.
 
-This will install Shuup and its dependencies into your virtualenv.
+.. note::
+   Shuup uses ``django-parler`` for model translations. Please ensure
+   ``PARLER_DEFAULT_LANGUAGE_CODE`` is set. See `django-parler configuration
+   <http://django-parler.readthedocs.io/en/latest/configuration.html>`_ for more
+   details.
+
+.. note::
+   Shuup uses the ``LANGUAGES`` setting to render multilingual forms. You'll likely
+   want to override this setting to restrict your applications supported languages.
 
-After this, you can begin setting up a Django project using whichever
-standards you fancy.
+5. Once you have configured the Shuup apps you would like to use, run the
+   following commands to create the database and initialize Shuup
+
+   .. code-block:: shell
+
+      python manage.py migrate
+      python.manage.py shuup_init
 
 Shuup Packages
 --------------
@@ -35,17 +74,58 @@ Shuup is a constellation of Django apps, with many delivered in the single
 "Shuup Base" distribution, and with additional apps available as separate
 downloads.
 
-The core package all Shuup installations will require is ``shuup.core``.
+``shuup.core`` is the core package required by all Shuup installations.
 It contains the core business logic for e-commerce, and all of the database
 models required. However, it contains no frontend or admin dashboard, as
 different projects may wish to replace them with other components or even
 elide them altogether.
 
-A default frontend, a basic but fully featured storefront, is included, as
-the application ``shuup.front``. It itself has several sub-applications that
-may be used to toggle functionality on and off.
+``shuup.front`` is a basic but fully featured storefront. It itself has
+several sub-applications that may be used to toggle functionality on and off.
+
+* ``shuup.front.apps.auth`` is a wrapper around django auth for login and
+  password recovery.
+* ``shuup.front.apps.registration`` provides views for customer activation
+  and registration.
+* ``shuup.front.apps.customer_information`` provides views for customer
+  address management.
+* ``shuup.front.apps.personal_order_history`` adds views for customer
+  order history.
+*  ``shuup.front.apps.simple_order_notification`` can be used to send
+   email notifications to the customer upon order completion.
+* ``shuup.front.apps.simple_search`` provides basic product search
+  functionality.
+
+``shuup.admin`` provides a fully featured administration dashboard.
+
+``shuup.addons`` can be used to install and manage Shuup addons.
+
+``shuup.api`` exposes SHUUP APIs as RESTful url endpoints. See the
+:doc:`web API documentation <web_api>` for details.
+
+``shuup.campaigns`` provides a highly customizable promotion and discount
+management system.
+
+``shuup.customer_group_pricing`` can be used to customize product pricing by
+customer contact groups.
+
+``shuup.default_tax`` is a rules-based tax module that calculates and applies
+taxes on orders. See the :doc:`prices and taxes documentation
+<prices_and_taxes>` for details.
+
+``shuup.guide`` integrates search results from this documentation into Admin
+search.
+
+``shuup.notify`` is a generic notification framework that can be used to
+inform users about various events (order creation, shipments, password
+resets, etc). See the :doc:`notification documentation
+<notify_specification>` for details.
+
+``shuup.order_printouts`` adds support to create PDF printouts of orders from
+admin.
 
-.. TODO:: Describe the sub-apps.
+``shuup.simple_cms`` is a basic content management system that can be used to
+add pages to the storefront.
 
-A fully featured administration dashboard is also included as the application
-``shuup.admin``.
+``shuup.simple_supplier`` is a simple inventory management system that can be
+used to keep track of product inventory.

doc/getting_started_dev.rst

@@ -3,8 +3,15 @@ Getting Started with Shuup Development
 
 .. note::
 
-   If you are planning on using Shuup for developing your own shop,
-   read the :doc:`other Getting Started guide <getting_started>` instead.
+   If you are planning on using Shuup to build your own shop,
+   read the :doc:`Getting Started with Shuup guide <getting_started>`
+   instead.
+
+Requirements
+------------
+* Python 2.7.9+/3.4+. https://www.python.org/download/.
+* Node.js. https://nodejs.org/en/download/
+* Any database supported by Django.
 
 Installation for Shuup Development
 ----------------------------------
@@ -13,32 +20,31 @@ To start developing Shuup, you'll need a Git checkout of Shuup and a
 Github fork of Shuup for creating pull requests.  Github pull requests
 are used to get your changes into Shuup Base.
 
- 1. If you haven't done so already, create a fork of Shuup in Github by
-    clicking the "Fork" button at https://github.com/shuup/shuup and
-    clone the fork to your computer as usual. See `Github Help about
-    forking repos <https://help.github.com/articles/fork-a-repo/>`__ for
-    details.
+1. If you haven't done so already, create a fork of Shuup in Github by
+   clicking the "Fork" button at https://github.com/shuup/shuup and
+   clone the fork to your computer as usual. See `Github Help about
+   forking repos <https://help.github.com/articles/fork-a-repo/>`__ for
+   details.
 
- 2. Setup a virtualenv and activate it.  You may use the traditional
-    ``virtualenv`` command, or the newer ``python -m venv`` if you're
-    using Python 3.  See `Virtualenv User Guide
-    <https://virtualenv.pypa.io/en/latest/userguide.html>`__, if you
-    don't know virtualenv already.  For example, following commands
-    create and activate a virtualenv in Linux:
+2. Setup a virtualenv and activate it.  You may use the traditional
+   ``virtualenv`` command, or the newer ``python -m venv`` if you're
+   using Python 3.  See `Virtualenv User Guide
+   <https://virtualenv.pypa.io/en/latest/userguide.html>`__, if you
+   are unfamiliar with virtualenv.  For example, following commands
+   create and activate a virtualenv in Linux:
 
-    .. code-block:: shell
+   .. code-block:: shell
 
-       virtualenv shuup-venv
-       . shuup-venv/bin/activate
+      virtualenv shuup-venv
+      . shuup-venv/bin/activate
 
- 3. Finally, you'll need to install Shuup in the activated virtualenv in
-    development mode.  To do that, run the following commands in the
-    root of the checkout (within the activated virtualenv):
+3. Finally, you'll need to install Shuup in the activated virtualenv in
+   development mode.  To do that, run the following commands in the
+   root of the checkout (within the activated virtualenv):
 
-    .. code-block:: shell
+   .. code-block:: shell
 
-       pip install -e .
-       python setup.py build_resources
+      pip install -e .[everything]
 
 Workbench, the built-in test project
 ------------------------------------
@@ -95,9 +101,9 @@ To run tests in the active virtualenv:
 
 .. code-block:: shell
 
-   py.test -v shuup_tests
+   py.test -v --nomigrations shuup_tests
    # Or with coverage
-   py.test -vvv --cov shuup --cov-report html shuup_tests
+   py.test -vvv --nomigrations --cov shuup --cov-report html shuup_tests
 
 To run tests for all supported Python versions run:
 
@@ -116,12 +122,3 @@ the ``shuup`` directory:
 .. code-block:: shell
 
    cd shuup && python -m shuup_workbench shuup_makemessages
-
-Docstring coverage
-------------------
-
-The DocCov script is included for calculating some documentation coverage metrics.
-
-.. code-block:: shell
-
-   python _misc/doccov.py shuup/core -o doccov.html