Document the new US sample site

- Rework the page on applying taxes in the US
- Update the release notes
- Update the "sandbox" page with details of the new site

docs/source/howto/how_to_handle_us_taxes.rst

@@ -19,32 +19,29 @@ for further guidance on how to replace strategies.
 Adjust checkout views to apply taxes once they are known
 --------------------------------------------------------
 
-Second, the :class:`~oscar.apps.checkout.views.PaymentDetailsView`
-checkout view should be overridden within your project to calculate taxes on
-the basket within the
-:func:`~oscar.apps.checkout.views.PaymentDetailsView.build_submission` method.
+Second, the :class:`~oscar.apps.checkout.session.CheckoutSessionMixin`
+should be overridden within your project to apply taxes
+to the submission.
 
 .. code-block:: python
 
-    from oscar.apps.checkout import views
+    from oscar.apps.checkout import session
 
     from . import tax
 
-    # Override the core Oscar view class
-    class PaymentDetailsView(views.PaymentDetailsView):
-        
-        # Override build_submission to ensure taxes are applied before
-        # attempting to place an order
+    class CheckoutSessionMixin(session.CheckoutSessionMixin):
+
         def build_submission(self, **kwargs):
-            submission = super(PaymentDetailsView, self).build_submission(**kwargs)
+            submission = super(CheckoutSessionMixin, self).build_submission(
+                **kwargs)
 
-            # Apply taxes (in place)
-            tax.apply_to_submission(submission)
+            if submission['shipping_address']:
+                tax.apply_to(submission)
 
-            # Recalculate order total to ensure we have a tax-inclusive total
-            submission['order_total'] = self.get_order_totals(
-                submission['basket'],
-                shipping_method=submission['shipping_method'])
+                # Recalculate order total to ensure we have a tax-inclusive total
+                submission['order_total'] = self.get_order_totals(
+                    submission['basket'],
+                    shipping_method=submission['shipping_method'])
 
             return submission
 
@@ -54,7 +51,7 @@ An example implementation of the ``tax.py`` module is:
 
     from decimal import Decimal as D
 
-    def apply_tax_to_submission(submission):
+    def apply_to(submission):
         # Assume 7% sales tax on sales to New Jersey  You could instead use an
         # external service like Avalara to look up the appropriates taxes.
         STATE_TAX_RATES = {
@@ -67,7 +64,7 @@ An example implementation of the ``tax.py`` module is:
             line_tax = calculate_tax(
                 line.line_price_excl_tax_incl_discounts, rate)
             unit_tax = (line_tax / line.quantity).quantize(D('0.01'))
-            line.stockinfo.price.tax = unit_tax
+            line.purchase_info = unit_tax
 
         # Note, we change the submission in place - we don't need to
         # return anything from this function
@@ -78,3 +75,8 @@ An example implementation of the ``tax.py`` module is:
         def calculate_tax(price, rate):
             tax = price * rate
             return tax.quantize(D('0.01'))
+
+.. tip::
+
+   Oscar's repository contains a sample Oscar site customised for the US.  See
+   :ref:`us_site` for more information.

docs/source/internals/sandbox.rst

@@ -2,8 +2,9 @@
 Sample Oscar projects
 =====================
 
-Oscar ships with two sample projects: a 'sandbox' site, which is a vanilla
-install of Oscar using the default templates and styles, and a fully featured
+Oscar ships with three sample projects: a 'sandbox' site, which is a vanilla
+install of Oscar using the default templates and styles, a sample US site which
+customises Oscar to use US style taxes, and a fully featured
 'demo' site which demonstrates how Oscar can be re-skinned and customised to
 model a domain.
 
@@ -30,35 +31,8 @@ are domain-specific.  For instance:
 
 The sandbox is, in effect, the blank canvas upon which you can build your site.
 
-The demo site
--------------
-
-The demo site is *the* reference Oscar project as it illustrates how Oscar can
-be redesigned and customised to build an realistic e-commerce store. The demo
-site is a sailing store selling a range of different product types.
-
-The customisations on top of core Oscar include:
-
-* A new skin
-* A variety of product types including books, clothing and downloads
-* Payment with PayPal Express using django-oscar-paypal_.
-* Payment with bankcards using Datacash using django-oscar-datacash_.
-
-.. _django-oscar-paypal: https://github.com/tangentlabs/django-oscar-paypal
-.. _django-oscar-datacash: https://github.com/tangentlabs/django-oscar-datacash
-
-.. note::
-
-    Both the sandbox and demo site have the Django admin interface wired up.
-    This is done as a convenience for developers to browse the model instances.
-
-    Having said that, the Django admin interface is *unsupported* and will fail
-    or be of little use for some models. At the time of writing, editing
-    products in the admin is clunky and slow, and editing categories is
-    not supported at all.
-
 Browse the external sandbox site
-================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An instance of the sandbox site is build hourly from master branch and made
 available at http://latest.oscarcommerce.com 
@@ -68,15 +42,9 @@ available at http://latest.oscarcommerce.com
     It is possible for users to access the dashboard and edit the site content.
     Hence, the data can get quite messy.  It is periodically cleaned up.
 
-Browse the external demo site
-=============================
 
-An instance of the demo site is built periodically (but not automatically) and
-available at http://demo.oscarcommerce.com. It is typically updated when new
-versions of Oscar are released.
-
-Running the sandbox locally
-===========================
+Run the sandbox locally
+~~~~~~~~~~~~~~~~~~~~~~~
 
 It's pretty straightforward to get the sandbox site running locally so you can
 play around with Oscar.
@@ -112,8 +80,65 @@ at: http://localhost:8000.  A sample superuser is installed with credentials::
     email: superuser@example.com
     password: testing
 
-Running the demo locally
-========================
+.. _us_site:
+
+The US site
+-----------
+
+The US site is a relatively simple Oscar that makes a few key customisations in
+order to mimic how sites in the US work. Specifically, it:
+
+- Overrides the partner app to supply a new strategy selector which ensures all
+  prices are return without taxes.
+
+- Overrides the checkout app in order to apply taxes to submissions once the
+  shipping address is known.
+
+To browse the US site locally run:
+
+.. code-block:: bash
+
+   (oscar) $ make us_site
+   (oscar) $ sites/us/manage.py runserver
+
+and the US site will be browsable at http://localhost:8000
+
+The demo site
+-------------
+
+The demo site is *the* reference Oscar project as it illustrates how Oscar can
+be redesigned and customised to build an realistic e-commerce store. The demo
+site is a sailing store selling a range of different product types.
+
+The customisations on top of core Oscar include:
+
+* A new skin
+* A variety of product types including books, clothing and downloads
+* Payment with PayPal Express using django-oscar-paypal_.
+* Payment with bankcards using Datacash using django-oscar-datacash_.
+
+.. _django-oscar-paypal: https://github.com/tangentlabs/django-oscar-paypal
+.. _django-oscar-datacash: https://github.com/tangentlabs/django-oscar-datacash
+
+.. note::
+
+    Both the sandbox and demo site have the Django admin interface wired up.
+    This is done as a convenience for developers to browse the model instances.
+
+    Having said that, the Django admin interface is *unsupported* and will fail
+    or be of little use for some models. At the time of writing, editing
+    products in the admin is clunky and slow, and editing categories is
+    not supported at all.
+
+Browse the external demo site
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An instance of the demo site is built periodically (but not automatically) and
+available at http://demo.oscarcommerce.com. It is typically updated when new
+versions of Oscar are released.
+
+Run the demo site locally
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Assuming you've already set-up the sandbox site, there are two further services
 required to run the demo site:

docs/source/releases/v0.8.rst

@@ -15,6 +15,8 @@ Table of contents:
 Overview
 ========
 
+Oscar now has a demo site customised for the US!
+
 .. _compatibility:
 
 Compatibility
@@ -55,6 +57,16 @@ overridden like most other classes in Oscar; overriding the related
 Application instance is not necessary any more. Updated instructions are
 available in :doc:`/topics/customisation`.
 
+US demo site
+------------
+
+To help developers building sites for the US, a new example Oscar site has been
+included in the repo. This customises core Oscar to treat all prices as
+excluding tax and then calculate and apply taxes once the shipping address is
+known.
+
+See :ref:`us_site` for more information.
+
 .. _minor_changes:
 
 Minor changes