Tidied docs

docs/source/customisation.rst

@@ -57,15 +57,11 @@ tries to load the ``Item`` class, it will load the one from your local project.
 All views are class-based
 -------------------------
 
-This enables any view to be subclassed and extended within your project.
+This enables any view to be subclassed and extended within your project.  
 
 Templates can be overridden
 ---------------------------
 
-This is a simple technique relying on the fact that the template loader can be
-configured to look in your project first for oscar templates.
-
-
-Oscar's is designed to be open to customisation wherever possible.  There are two
-main ways in which this is acheived.
-
+This is a common technique relying on the fact that the template loader can be
+configured to look in your project first for templates, before it uses the defaults
+from oscar.

docs/source/getting_started.rst

@@ -6,16 +6,69 @@ Install using::
 
     pip install django-oscar
 
+then add::
+
+    'oscar.apps.basket.middleware.BasketMiddleware'
+
+to ``MIDDLEWARE_CLASSES``, and::
+
+    'oscar.apps.promotions.context_processors.promotions',
+    'oscar.apps.checkout.context_processors.checkout',
+
+to ``TEMPLATE_CONTEXT_PROCESSORS``.  Next, add the following apps
+to your ``INSTALLED_APPS``::
+
+    'oscar',
+    'oscar.apps.analytics',
+    'oscar.apps.discount',
+    'oscar.apps.order',
+    'oscar.apps.checkout',
+    'oscar.apps.shipping',
+    'oscar.apps.order_management',
+    'oscar.apps.catalogue',
+    'oscar.apps.catalogue.reviews',
+    'oscar.apps.basket',
+    'oscar.apps.payment',
+    'oscar.apps.offer',
+    'oscar.apps.address',
+    'oscar.apps.partner',
+    'oscar.apps.customer',
+    'oscar.apps.promotions',
+    'oscar.apps.reports',
+    'oscar.apps.search',
+    'oscar.apps.voucher',
+
+Add::
+
+    from oscar.defaults import *
+
+to your ``settings`` module and run::
+
+    python manage.py syncdb
+
+to create the database tables.
+
+
 Demo shop
 ---------
 
-If you just want to have a play around, do the following:
+A demo shop is in preparation at the moment and will be available soon.  
 
 Real shop
 ---------
 
-Unfortunately, setting up an e-commerce store is never trivial and there
-are several further steps you will want to follow:
+Sadly, setting up an e-commerce store is never trivial as you would like.  At a
+minimum, you'll have to consider the following questions:
+
+* How are shipping charges calculated?
+* How are products organised into categories?
+* How are stock messages determined?
+* How is payment taken at checkout?
+* How are orders fulfilled and managed?
+* How is stock and inventory updated?
+
+Much of the documentation for oscar is organised as recipes that explain
+how to solve questions such as those above:
 
 * :doc:`recipes/how_to_customise_models`
 * :doc:`recipes/how_to_override_a_core_class`

docs/source/index.rst

@@ -1,20 +1,22 @@
-
-   sphinx-quickstart on Mon Feb  7 13:16:33 2011.
+.. sphinx-quickstart on Mon Feb  7 13:16:33 2011.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
 ==================================================
 django-oscar - Domain-driven e-commerce for Django
 ==================================================
 
-django-oscar (henceforth, Oscar) is an e-commerce framework for Django designed
-for building domain-driven applications.  It is structured in way that lets any
-part of the core functionality be customised to suit the needs of your project.
-In this way, the core structure of your application can match the domain at
-hand.
+django-oscar is an e-commerce framework for Django designed for building
+domain-driven applications.  It is structured so that the core business objects
+(eg the models for a product/basket/order etc) can be customised to suit the
+domain at hand.  In this way, your application can accurately model its domain,
+making feature development and maintenance much easier.
+
+This is in contrast to alternative e-commerce frameworks which use meta-data and
+key-value tables to model a domain.
 
 Oscar is developed by `Tangent Labs`_, a London-based digital agency.  It is used in
-production in several applications to sell everything from beer mats to ipads
+production in several applications to sell everything from beer mats to ipads.
 
 .. _`Tangent Labs`: http://www.tangentlabs.co.uk
 

docs/source/recipes.rst

@@ -2,10 +2,18 @@ Recipes
 ============
 
 Recipes are simple guides to solving common problems that occur when creating
-ecommerce projects.
+e-commerce projects.
 
-.. toctree::
-   :maxdepth: 2
+Customisation
+-------------
 
-   recipes/custom_shipping_logic
-   recipes/enforcing_stock_rules
+* :doc:`recipes/how_to_customise_models`
+* :doc:`recipes/how_to_override_a_core_class`
+
+Checkout
+--------
+
+* :doc:`recipes/custom_shipping_logic`
+* :doc:`recipes/enforcing_stock_rules`
+
+Lots more to come!

docs/source/recipes/how_to_customise_models.rst

@@ -2,4 +2,30 @@
 How to customise models
 =======================
 
+You must first create a local version of the app that you wish to customise.  This
+involves creating a local app with the same name and importing the equivalent models
+from oscar into it.
+
+Example
+-------
+
+Suppose you want to add a video_url field to the core product model.  This means that
+you want your application to use a subclass of ``oscar.apps.catalogue.models.Product`` which
+has an additional field.
+
+The first step is to create a local version of the "catalogue" app.  At a minimum, this 
+involves creating ``catalogue/models.py`` within your project and changing ``INSTALLED_APPS``
+to point to your local version rather than oscar's.  
+
+Next, you can modify the ``Product`` model through subclassing::
+
+    # yourproject/catalogue/models.py
+
+    from oscar.apps.catalogue.abstract_models import AbstractProduct
+
+    class Product(AbstractProduct):
+        video_url = models.URLField()
+
+Now, running ``./manage.py syncdb`` will create the product model with your additional field
+
 

docs/source/recipes/how_to_override_a_core_class.rst

@@ -0,0 +1,39 @@
+============================
+How to override a core class
+============================
+
+Example
+-------
+
+Suppose you want to alter the way order number's are generated.  By default,
+the class ``oscar.apps.order.utils.OrderNumberGenerator`` is used.  To change
+the behaviour, you need to ensure that you have a local version of the
+``order`` app (ie ``INSTALLED_APPS`` should contain ``yourproject.order``, not
+``oscar.apps.order``).  Then create a class within your ``order`` app which
+matches the module path from oscar: ``order.utils.OrderNumberGenerator``.  This
+could subclass the class from oscar or not.  An example implementation is::
+
+    # yourproject/order/utils.py
+    
+    from oscar.apps.order.utils import OrderNumberGenerator as CoreOrderNumberGenerator
+
+
+    class OrderNumberGenerator(CoreOrderNumberGenerator):
+        
+        def order_number(self, basket=None):
+            num = super(OrderNumberGenerator, self).order_number(basket)
+            return "SHOP-%s" % num
+
+the same module path as the one from oscar, that is, 
+
+Discussion
+----------
+
+This principle of overriding classes from modules is an important feature of oscar
+and makes it easy to customise virtually any functionality from the core.  For this
+to work, you must ensure that:
+
+1. You have a local version of the app, rather than using oscar's directly
+2. Your local class has the same module path relative to the app as the oscar
+   class being overridden
+

docs/source/reference/settings.rst

@@ -14,7 +14,7 @@ Available settings
 OSCAR_DEFAULT_CURRENCY
 ----------------------
 
-Default: None (This is a required field)
+Default: ``None`` (This is a required field)
 
 This should be the symbol of the currency you wish Oscar to use by default.
 
@@ -28,7 +28,7 @@ The time to live for the basket cookie in seconds
 OSCAR_IMAGE_FOLDER
 ------------------
 
-Default: images/products/%Y/%m/ 
+Default: ``images/products/%Y/%m/``
 
 The path for uploading images to.