Add documentation for sandbox setup

Author: Sebastian Vetter

Makefile

@@ -0,0 +1,9 @@
+.PHONY: tests docs
+
+docs:
+	${MAKE} -C docs html
+
+
+tests:
+	py.test --pep8 --cov oscar_mws
+	py.test -m integration

docs/source/getting_started.rst

@@ -5,8 +5,8 @@ Getting Started
 Basic Concepts
 --------------
 
-*django-oscar-mws* provides a few models that represent data retrieved from or
-sent to Amazon's MWS API.
+*django-oscar-mws* (OMWS) provides a few models that represent data retrieved
+from or sent to Amazon's MWS API.
 
 
 Merchant Account
@@ -61,3 +61,84 @@ of assumptions that we have to make based on the way MWS works.
    is marked as shipped if the stock record is tracking MWS stock. This
    functionality is encapsulated in ``AmazonStockRecordMixin`` which you should
    add to your projects ``StockRecord``.
+
+
+Setting Up The Sandbox
+----------------------
+
+*django-oscar-mws* comes with a sandbox site that shows how MWS can be
+integrated with Oscar. It resembles a basic set up of Oscar with an
+out-of-the-box integration of MWS. This section will walk you through setting
+the sandbox up locally and how to make it interact with the MWS API.
+
+.. note:: Oscar itself has quite a few dependencies and settings that might
+    cause some problems when you are setting up the MWS sandbox. In addition to
+    this documentation you might also want to check out the `Oscar docs on
+    setting up a project`_.
+
+The first thing to do is cloning the repository and installing it's
+requirements which will includes setting up Oscar. It also creates a new
+database (if it doesn't exist) creates the required tables:
+
+.. code-block:: bash
+
+   $ git clone [email protected]:tangentlabs/django-oscar-mws.git
+   $ cd django-oscar-mws
+   $ mkvirtualenv mws  # requires virtualenvwrapper to be installed
+   $ make sandbox
+
+By default, the sandbox is using Oscar's precompiled *CSS* files by setting
+``USE_LESS = False``. If you want to use *LESS* to generate the CSS yourself,
+take a look at the documentation on `how to use LESS with Oscar`_.
+
+Create Admin User
+~~~~~~~~~~~~~~~~~
+
+The main interface for MWS lives in Oscar's dashboard and therefore requires an
+admin user to login. Create a new admin account using Django's
+``createsuperuser`` command and follow the instruction:
+
+.. code-block:: bash
+
+    $ ./sandbox/manage.py createsuperuser
+
+You should now be able to run the sandbox locally using Django's builtin
+HTTP server:
+
+.. code-block:: bash
+
+   $ ./sandbox/manage.py runserver
+
+You now have a sample shop up and running and should be able to `navigate to
+the dashboard`_ to continue the setup of your MWS credentials.
+
+
+Setting Up MWS
+--------------
+
+The API endpoints provided by Amazon MWS differ based on the MWS region. The
+different `regions and endpoints`_ are detailed in the Amazon docs. Each region
+requires separate MWS credentials for each account. In OMWS, these accounts are
+called *merchant accounts* and are used to identify the endpoints to use when
+communication with MWS.
+
+You have to create a merchant account and provide your MWS credentials to be
+able to connect to MWS. Head to the *Amazon MWS > Merchants & Marketplaces* in
+the Oscar dashboard and select 'Add merchant account'. A corresponding partner
+account in Oscar is required for a MWS merchant account, however, if no partner
+is selected explicitly, a new one will be created automatically with the same
+name as the MWS merchant account.
+
+With your merchant account(s) added, you can update the corresponding
+marketplaces in the drop-down menu on the right-hand side. This will pull the
+MWS marketplaces that you are able to trade in from MWS. This will also
+indicate that communicating with the MWS API is successful.
+
+
+.. _`navigate to the dashboard`: http://localhost:8000/dashboard/merchants/
+
+.. _`regions and endpoints`: http://docs.developer.amazonservices.com/en_US/dev_guide/DG_Registering.html
+
+.. _`Oscar docs on setting up a project`: http://django-oscar.readthedocs.org/en/latest/internals/sandbox.html#sample-oscar-projects
+
+.. _`how to use LESS with Oscar`: http://django-oscar.readthedocs.org/en/latest/howto/how_to_handle_statics.html?highlight=less#less-css