Skip to content
This repository
Browse code

Updated documentation - still not complete but much better

  • Loading branch information...
commit 9727c7063a018fb10da4d0783c6ad0c4139a3ec8 1 parent fe4bcd5
David Winterbottom authored
20  README.rst
Source Rendered
@@ -10,12 +10,19 @@ core functionality can be customised to suit the needs of your project.  This
10 10
 allows it to handle a wide range of e-commerce requirements, from large-scale B2C
11 11
 sites to complex B2B sites rich in domain-specific business logic.
12 12
 
13  
-Oscar is used in production by:
  13
+Case studies
  14
+------------
14 15
 
15  
-* Tata - http://www.landmarkonthenet.com
16  
-* Carlsberg - Their global "We deliver more" platform is powered by Oscar.
  16
+Oscar is still in active development, but is used in production by a range of
  17
+companies, from large multinationals to small, boutique stores:
  18
+
  19
+* Tata Group - http://www.landmarkonthenet.com
  20
+* Carlsberg - Their global "We Deliver More" platform is powered by Oscar (but
  21
+  is a B2B site so it not browsable by the public).
17 22
 * Dolbeau - http://www.dolbeau.ca/
18  
-* The UK Labour party
  23
+* The UK Labour party - http://shop.labour.org.uk (will be live in early June)
  24
+
  25
+Many more on the way.
19 26
 
20 27
 This README is just a stub - see the following links for more details
21 28
 information:
@@ -23,6 +30,7 @@ information:
23 30
 * `Official homepage`_ 
24 31
 * `Demo site`_ (experimental) 
25 32
 * `Documentation`_ on `readthedocs.org`_
  33
+* `Google Group`_ - the mailing list is django-oscar@googlegroups.com
26 34
 * `Continuous integration homepage`_ on `travis-ci.org`_
27 35
 * `Twitter account for news and updates`_
28 36
 * `Twitter account of all commits`_
@@ -37,10 +45,14 @@ information:
37 45
 .. _`travis-ci.org`: http://travis-ci.org/
38 46
 .. _`Twitter account for news and updates`: https://twitter.com/#!/django_oscar
39 47
 .. _`Twitter account of all commits`: https://twitter.com/#!/oscar_django
  48
+.. _`Google Group`: https://groups.google.com/forum/?fromgroups#!forum/django-oscar
40 49
 
41 50
 Oscar was written by `David Winterbottom`_ (`@codeinthehole`_) and is developed
42 51
 and maintained by `Tangent Labs`_, a London-based digital agency.
43 52
 
  53
+Oscar is released under the permissive `New BSD license`_.
  54
+
44 55
 .. _`David Winterbottom`: http://codeinthehole.com
45 56
 .. _`@codeinthehole`: https://twitter.com/codeinthehole
46 57
 .. _`Tangent Labs`: http://www.tangentlabs.co.uk
  58
+.. _`New BSD license`: https://github.com/tangentlabs/django-oscar/blob/master/LICENSE
16  docs/source/components.rst
Source Rendered
... ...
@@ -1,16 +0,0 @@
1  
-==========
2  
-Components
3  
-==========
4  
-
5  
-This section provides high-level descriptions of the main components of django-oscar.
6  
-
7  
-Contents:
8  
-
9  
-.. toctree::
10  
-   :maxdepth: 2
11  
-
12  
-   components/offers
13  
-   components/checkout
14  
-   components/shipping
15  
-   components/analytics
16  
-   components/promotions
72  docs/source/contributing.rst
Source Rendered
@@ -2,15 +2,69 @@
2 2
 Contributing
3 3
 ============
4 4
 
5  
-* New features should be discussed on the mailing list (or in the meetings) before serious work starts
6  
-* Pull requests will be rejected if sufficient tests aren't provided
7  
-* Please update the documentation when altering behaviour or introducing new features 
  5
+Some ground rules:
8 6
 
9  
-Contents:
  7
+* To avoid disappointment, new features should be discussed on the mailing list
  8
+  (django-oscar@googlegroups.com) before serious work starts.
10 9
 
11  
-.. toctree::
12  
-   :maxdepth: 2
  10
+* Pull requests will be rejected if sufficient tests aren't provided.
13 11
 
14  
-   contributing/installation
15  
-   contributing/testing
16  
-   contributing/conventions
  12
+* Please update the documentation when altering behaviour or introducing new features.
  13
+
  14
+* Follow the conventions (see below).
  15
+
  16
+Installation
  17
+============
  18
+
  19
+From zero to tests passing in 2 minutes (most of which is PIL installing)::
  20
+
  21
+    git clone git@github.com:<username>/django-oscar.git
  22
+    cd django-oscar
  23
+    mkvirtualenv oscar
  24
+    ./setup.py develop
  25
+    pip install -r requirements.txt
  26
+    ./run_tests.py
  27
+
  28
+Writing docs
  29
+============
  30
+
  31
+There's a helper script for building the docs locally::
  32
+
  33
+    cd docs
  34
+    ./test_docs.sh
  35
+
  36
+Conventions
  37
+===========
  38
+
  39
+General
  40
+-------
  41
+
  42
+* PEP8 everywhere while remaining sensible
  43
+
  44
+URLs
  45
+----
  46
+
  47
+* List pages should use plurals, eg ``/products/``, ``/notifications/``
  48
+
  49
+* Detail pages should simply be a PK/slug on top of the list page, eg
  50
+  ``/products/the-bible/``, ``/notifications/1/``
  51
+  
  52
+* Create pages should have 'create' as the final path segment, eg
  53
+  ``/dashboard/notifications/create/``
  54
+
  55
+* Update pages are sometimes the same as detail pages (ie when in the
  56
+  dashboard).  In those cases, just use the detail convention, eg
  57
+  ``/dashboard/notifications/3/``.  If there is a distinction between the detail
  58
+  page and the update page, use ``/dashboard/notifications/3/update/``.
  59
+
  60
+* Delete pages, eg /dashboard/notifications/3/delete/
  61
+
  62
+View class names
  63
+----------------
  64
+
  65
+Classes should be named according to::
  66
+
  67
+    '%s%sView' % (class_name, verb)
  68
+
  69
+For example, ``ProductUpdateView``, ``OfferCreateView`` and
  70
+``PromotionDeleteView``.  This doesn't fit all situations but it's a good basis.
0  docs/source/customisation.rst → docs/source/design_decisions.rst
Source Rendered
File renamed without changes
197  docs/source/getting_started.rst
Source Rendered
... ...
@@ -1,76 +1,171 @@
1  
-===============
2  
-Getting started
  1
+============================
  2
+Start building your own shop
  3
+============================
  4
+
  5
+For simplicity, let's assume you're building a new e-commerce project from
  6
+scratch and have decided to use Oscar.  Let's call this shop 'frobshop'
  7
+
  8
+.. tip::
  9
+
  10
+    You can always review the set-up of the `Sandbox site`_ in case you have
  11
+    trouble following the below instructions.
  12
+
  13
+.. _`Sandbox site`: https://github.com/tangentlabs/django-oscar/tree/releases/0.2/sandbox
  14
+
  15
+Install by hand
3 16
 ===============
4 17
 
5  
-Install using::
  18
+Install oscar (which will install Django as a dependency), then create the
  19
+project::
6 20
 
7 21
     pip install django-oscar
  22
+    django-admin.py startproject frobshop
  23
+
  24
+This will create a folder ``frobshop`` for your project.
  25
+
  26
+Settings
  27
+--------
  28
+
  29
+Now edit your settings file ``frobshop.frobshop.settings.py`` to specify a
  30
+database (we use sqlite for simplicity)::
  31
+
  32
+    DATABASES = {
  33
+        'default': {
  34
+            'ENGINE': 'django.db.backends.sqlite3',
  35
+            'NAME': 'db.sqlite3',
  36
+            'USER': '',
  37
+            'PASSWORD': '',
  38
+            'HOST': '',
  39
+            'PORT': '',
  40
+        }
  41
+    }
  42
+
  43
+then add ``oscar.apps.basket.middleware.BasketMiddleware`` to ``MIDDLEWARE_CLASSES``, and
  44
+set ``TEMPLATE_CONTEXT_PROCESSORS`` to::
  45
+
  46
+    TEMPLATE_CONTEXT_PROCESSORS = (
  47
+        "django.contrib.auth.context_processors.auth",
  48
+        "django.core.context_processors.request",
  49
+        "django.core.context_processors.debug",
  50
+        "django.core.context_processors.i18n",
  51
+        "django.core.context_processors.media",
  52
+        "django.core.context_processors.static",
  53
+        "django.contrib.messages.context_processors.messages",
  54
+        'oscar.apps.search.context_processors.search_form',
  55
+        'oscar.apps.promotions.context_processors.promotions',
  56
+        'oscar.apps.checkout.context_processors.checkout',
  57
+        'oscar.core.context_processors.metadata',
  58
+    ) 
  59
+
  60
+Next, modify ``INSTALLED_APPS`` to be a list, add ``South`` and append Oscar's core apps::
8 61
 
9  
-then add::
  62
+    from oscar import get_core_apps
  63
+    INSTALLED_APPS = [
  64
+        'django.contrib.auth',
  65
+        ...
  66
+        'south',
  67
+    ] + get_core_apps()
10 68
 
11  
-    'oscar.apps.basket.middleware.BasketMiddleware'
  69
+and set your auth backends to::
12 70
 
13  
-to ``MIDDLEWARE_CLASSES``, and::
  71
+    AUTHENTICATION_BACKENDS = (
  72
+        'oscar.apps.customer.auth_backends.Emailbackend',
  73
+        'django.contrib.auth.backends.ModelBackend',
  74
+    )
14 75
 
15  
-    'oscar.apps.promotions.context_processors.promotions',
16  
-    'oscar.apps.checkout.context_processors.checkout',
  76
+to allow customers to sign in using an email address rather than a username.
17 77
 
18  
-to ``TEMPLATE_CONTEXT_PROCESSORS``.  Next, add the following apps
19  
-to your ``INSTALLED_APPS``::
  78
+Oscar currently uses Haystack for search so you need to specify::
20 79
 
21  
-    'oscar',
22  
-    'oscar.apps.analytics',
23  
-    'oscar.apps.discount',
24  
-    'oscar.apps.order',
25  
-    'oscar.apps.checkout',
26  
-    'oscar.apps.shipping',
27  
-    'oscar.apps.order_management',
28  
-    'oscar.apps.catalogue',
29  
-    'oscar.apps.catalogue.reviews',
30  
-    'oscar.apps.basket',
31  
-    'oscar.apps.payment',
32  
-    'oscar.apps.offer',
33  
-    'oscar.apps.address',
34  
-    'oscar.apps.partner',
35  
-    'oscar.apps.customer',
36  
-    'oscar.apps.promotions',
37  
-    'oscar.apps.reports',
38  
-    'oscar.apps.search',
39  
-    'oscar.apps.voucher',
  80
+    HAYSTACK_SITECONF = 'oscar.search_sites'
  81
+    HAYSTACK_SEARCH_ENGINE = 'dummy'
40 82
 
41  
-Add::
  83
+The last addition to the settings file is to import all of Oscar's default settings::
42 84
 
43 85
     from oscar.defaults import *
44 86
 
45  
-to your ``settings`` module and run::
  87
+URLs
  88
+----
  89
+
  90
+Alter your ``frobshop/urls.py`` to include Oscar's URLs::
  91
+
  92
+    from django.conf.urls import patterns, include, url
  93
+    from oscar.app import shop
  94
+
  95
+    urlpatterns = ('',
  96
+        (r'', include(shop.urls))
  97
+    )
  98
+
  99
+Database
  100
+--------
  101
+
  102
+Then create the database and the shop should be browsable::
  103
+
  104
+    python manage.py syncdb --noinput
  105
+    python manage.py migrate
  106
+
  107
+You should now have a running Oscar install that you can browse.
  108
+
  109
+
  110
+Install using Tangent's boilerplate django project
  111
+==================================================
  112
+
  113
+The easiest way to get started is to use Tangent's `template django project`_
  114
+although it is tailored to an Agency structure which may not suit everyone.
  115
+
  116
+.. `template django project`: https://github.com/tangentlabs/tangent-django-boilerplate
  117
+
  118
+Set up a virtualenv, and create a new project using the ``startproject``
  119
+management command::
  120
+
  121
+    mkvirtualenv frobshop
  122
+    pip install Django
  123
+    django-admin.py startproject frobshop \
  124
+        --template=https://github.com/tangentlabs/tangent-django-boilerplate/zipball/master 
46 125
 
47  
-    python manage.py syncdb
  126
+This will create a folder ``frobshop`` which is an entire templated project that
  127
+follows Tangent's conventions.  The structure is:
48 128
 
49  
-to create the database tables.
  129
+    frobshop/
  130
+        docs/
  131
+        www/
  132
+            conf/
  133
+            deploy/
  134
+            public/
  135
+            static/
  136
+            templates/
  137
+            manage.py
  138
+            settings.py
  139
+            settings_test.py
  140
+            urls.py
  141
+            urls_oscar.py
  142
+        README.rst
  143
+        fabconfig.py
  144
+        fabfile.py
  145
+        deploy-to-test.sh
  146
+        deploy-to-stage.sh
  147
+        deploy-to-prod.sh
50 148
 
  149
+Replace a few files with Oscar-specific versions::
51 150
 
52  
-Demo shop
53  
----------
  151
+    mv frobshop/www/urls{_oscar,}.py
  152
+    mv frobshop/www/deploy/requirements{_oscar,}.py
  153
+    mv frobshop/www/conf/default{_oscar,}.py
54 154
 
55  
-A demo shop is in preparation at the moment and will be available soon.
  155
+Install dependencies::
56 156
 
57  
-Real shop
58  
----------
  157
+    cd frobshop/www
  158
+    pip install -r deploy/requirements.txt
59 159
 
60  
-Sadly, setting up an e-commerce store is never trivial as you would like.  At a
61  
-minimum, you'll have to consider the following questions:
  160
+Create database::
62 161
 
63  
-* How are shipping charges calculated?
64  
-* How are products organised into categories?
65  
-* How are stock messages determined?
66  
-* How is payment taken at checkout?
67  
-* How are orders fulfilled and managed?
68  
-* How is stock and inventory updated?
  162
+    python manage.py syncdb -noinput
  163
+    python manage.py migrate
69 164
 
70  
-Much of the documentation for oscar is organised as recipes that explain
71  
-how to solve questions such as those above:
  165
+And that should be it.
72 166
 
73  
-* :doc:`recipes/how_to_customise_an_app`
74  
-* :doc:`recipes/how_to_customise_models`
75  
-* :doc:`recipes/how_to_override_a_core_class`
  167
+Next steps
  168
+==========
76 169
 
  170
+The next step is to implement the business logic of your domain on top of
  171
+Oscar.
56  docs/source/index.rst
Source Rendered
@@ -2,38 +2,60 @@
2 2
    You can adapt this file completely to your liking, but it should at least
3 3
    contain the root `toctree` directive.
4 4
 
5  
-==================================================
6  
-django-oscar - Domain-driven e-commerce for Django
7  
-==================================================
  5
+.. image:: http://img94.imageshack.us/img94/9094/oscarza.jpg
8 6
 
9  
-django-oscar is an e-commerce framework for Django designed for building
  7
+===================================
  8
+Domain-driven e-commerce for Django
  9
+===================================
  10
+
  11
+Oscar is an e-commerce framework for Django designed for building
10 12
 domain-driven applications.  It is structured so that the core business objects
11  
-(eg the models for a product/basket/order etc) can be customised to suit the
12  
-domain at hand.  In this way, your application can accurately model its domain,
13  
-making feature development and maintenance much easier.
  13
+can be customised to suit the domain at hand.  In this way, your application
  14
+can accurately model its domain, making feature development and maintenance
  15
+much easier.
14 16
 
15  
-This is in contrast to alternative e-commerce frameworks which use meta-data and
16  
-key-value tables to model a domain.
  17
+Features:
17 18
 
18  
-Oscar is developed by `Tangent Labs`_, a London-based digital agency.  It is used in
19  
-production in several applications to sell everything from beer mats to ipads.
  19
+* Any product type can be handled, including downloadable products,
  20
+  subscriptions, variant products (eg a T-shirt in different sizes and colours).
20 21
 
21  
-.. _`Tangent Labs`: http://www.tangentlabs.co.uk
  22
+* Customisable products, such as T-shirts with personalised messages.
22 23
 
23  
-The `source is on Github`_. 
  24
+* Can be used for large catalogues - Oscar is used in production by sites with
  25
+  more than 20 million products.
24 26
 
25  
-.. _`source is on Github`: https://github.com/tangentlabs/django-oscar
  27
+* Multiple fulfillment partners for the same product.
  28
+
  29
+* Range of merchandising blocks for promoting products throughuout your site.
  30
+
  31
+* Sophisticated offers that support virtually any kind of offer you can think
  32
+  of - multibuys, bundles, buy X get 50% of Y etc
  33
+
  34
+* Vouchers
26 35
 
27  
-Table of contents
28  
------------------
  36
+* Comprehensive dashboard
  37
+
  38
+* Support for split payment orders
  39
+
  40
+* Extension libraries available for PayPal, GoCardless, DataCash and more
  41
+
  42
+Oscar is developed by `Tangent Labs`_, a London-based digital agency.  It is
  43
+used in production in several applications to sell everything from beer mats to
  44
+ipads.  The `source is on Github`_. 
  45
+
  46
+.. _`Tangent Labs`: http://www.tangentlabs.co.uk
  47
+.. _`source is on Github`: https://github.com/tangentlabs/django-oscar
29 48
 
30 49
 .. toctree::
31 50
    :maxdepth: 2
32 51
 
  52
+   take_a_peek
33 53
    getting_started
34  
-   customisation
  54
+   key_questions
35 55
    recipes
  56
+   design_decisions
36 57
    reference
  58
+   contributing
37 59
 
38 60
 Indices and tables
39 61
 ==================
95  docs/source/introduction_to_ecommerce.rst
Source Rendered
... ...
@@ -1,95 +0,0 @@
1  
-================
2  
-eCommerce domain
3  
-================
4  
-
5  
-When building an e-commerce site, there are several components whose
6  
-implementation is strongly domain-specific.  That is, every site will have
7  
-different requirements for how such a component should operate.  As such, these components
8  
-cannot easily be modelled using a generic system - no configurable system will be able
9  
-to accurately capture all the domain-specific behaviour required.  
10  
-
11  
-The design philosophy of oscar is to not make a decision for you here, but to
12  
-provide the environment where any domain logic can be implemented, no matter
13  
-how complex.  This is achieved through the use of subclassable objects that can 
14  
-be tailored to your domain. 
15  
-
16  
-This document lists the components which will require implementation according to the
17  
-domain:
18  
-
19  
-Taxonomy
20  
---------
21  
-How are products organised within the site?  A common pattern is to have a single 
22  
-"category tree" where each product belongs to one category which sits within a tree structure
23  
-of other categories?
24  
-
25  
-However, there are lots of other options such as having several separate taxonomy trees (eg split by
26  
-brand, by theme, by product type).
27  
-
28  
-* Can a product belong to more than one category?
29  
-* Can a category sit in more than one place within the tree?  (eg a "children's fiction" category
30  
-  might sit beneath "children's books" and "fiction").
31  
-
32  
-Payment flow
33  
-------------
34  
-* Will the customer be debited at point of checkout, or when the items are dispatched?
35  
-* If charging after checkout, when are shipping charges collected?  
36  
-* What happens if an order is cancelled after partial payment?
37  
-
38  
-Payment sources
39  
----------------
40  
-How are customers going to pay for orders?  
41  
-
42  
-Will it be a simple, single-payment source solution such as paying by bankcard or using 
43  
-Google checkout?  Or something more complicated such as allowing payment to be split across
44  
-multiple payment sources such as a bankcard and a giftcard?
45  
-
46  
-More commonly, multiple payment sources can be used - such as:
47  
-
48  
-* Bankcard
49  
-* Google checkout
50  
-* PayPal
51  
-* Business account
52  
-* Managed budget
53  
-* No upfront payment but send invoices later
54  
-* Giftcard
55  
-
56  
-The checkout app within django-oscar is suitable flexible that all of these methods (and in 
57  
-any combination) is supported.  However, you will need to implement the logic for your domain
58  
-by subclassing the relevant view/util classes. 
59  
-
60  
-Domain logic is often required to: 
61  
-
62  
-* Determine which sources are available to an order;
63  
-* Determine if payment can be split across sources and in which combinations;
64  
-* Determine the order in which to take payment
65  
-
66  
-Stock logic
67  
------------
68  
-* Does the site support pre-orders (ordering before the product is available to be shipped) or
69  
-  back-orders (ordering when the product does not have stock)?  
70  
-
71  
-Availability
72  
-------------
73  
-* Based on the stock information from a fulfilment partner, what messaging should be 
74  
-  displayed on the site?  Further, should
75  
-
76  
-Shipping
77  
---------
78  
-Every client has a different requirement for shipping charges.  At its core, shipping charges
79  
-normall depend on the following:
80  
-
81  
-* Items in basket
82  
-* Shipping method chosen (e.g., standard or courier delivery)
83  
-* Dispatch method chosen (e.g., ship together or ship separately)
84  
-* Shipping address (e.g., which country it is in)
85  
-* Basket vouchers (e.g., a voucher which gives free delivery)
86  
-
87  
-Common questions:
88  
-
89  
-* Are items shipping together as one batch, or separately?
90  
-
91  
-Checkout
92  
---------
93  
-
94  
-
95  
-
167  docs/source/key_questions.rst
Source Rendered
... ...
@@ -0,0 +1,167 @@
  1
+==============================================
  2
+Building an e-commerce site: the key questions
  3
+==============================================
  4
+
  5
+When building an e-commerce site, there are several components whose
  6
+implementation is strongly domain-specific.  That is, every site will have
  7
+different requirements for how such a component should operate.  As such, these
  8
+components cannot easily be modelled using a generic system - no configurable
  9
+system will be able to accurately capture all the domain-specific behaviour
  10
+required.
  11
+
  12
+The design philosophy of Oscar is to not make a decision for you here, but to
  13
+provide the environment where any domain logic can be implemented, no matter how
  14
+complex.
  15
+
  16
+This document lists the components which will require implementation according
  17
+to the domain at hand.  These are the key questions to answer when building your
  18
+application.  Much of Oscar's documentation is in the form of "recipes" that
  19
+explain how to solve the questions listed here.  Each question links to the
  20
+relevant recipes.
  21
+
  22
+Catalogue
  23
+=========
  24
+
  25
+What are your product types?
  26
+----------------------------
  27
+
  28
+Are you selling books, DVDs, clothing, downloads or fruit and veg?  You will
  29
+need to capture the attributes of your product types within your models.  Oscar
  30
+divides products into 'product classes' which each have their own set of
  31
+attributes.  
  32
+
  33
+* :doc:`recipes/how_to_model_your_catalogue`
  34
+* :doc:`recipes/importing_a_catalogue`
  35
+
  36
+How is your catalogue organised?
  37
+--------------------------------
  38
+
  39
+How are products organised within the site?  A common pattern is to have a
  40
+single category tree where each product belongs to one category which sits
  41
+within a tree structure of other categories.  However, there are lots of other
  42
+options such as having several separate taxonomy trees (eg split by brand, by
  43
+theme, by product type).  Other questions to consider:
  44
+
  45
+* Can a product belong to more than one category?
  46
+* Can a category sit in more than one place within the tree?  (eg a "children's fiction" category
  47
+  might sit beneath "children's books" and "fiction").
  48
+
  49
+* :doc:`recipes/how_to_customise_an_app`
  50
+* :doc:`recipes/how_to_customise_models`
  51
+* :doc:`recipes/how_to_override_a_core_class`
  52
+
  53
+How are products managed?
  54
+-------------------------
  55
+
  56
+Is the catalogue managed by a admin using a dashboard, or though an automated
  57
+process, such as processing feeds from a fulfillment system?  Where are your
  58
+product images going to be served from?
  59
+
  60
+* :doc:`recipes/how_to_disable_an_app`
  61
+
  62
+
  63
+Pricing, stock and availability
  64
+===============================
  65
+
  66
+How is tax calculated?
  67
+----------------------
  68
+
  69
+What availability messages are shown to customers?
  70
+--------------------------------------------------
  71
+
  72
+Based on the stock information from a fulfilment partner, what messaging should be
  73
+displayed on the site?  
  74
+
  75
+* :doc:`recipes/how_to_configure_stock_messaging`
  76
+
  77
+Do you allow pre- and back-orders
  78
+---------------------------------
  79
+
  80
+An pre-order is where you allow a product to be bought before it has been
  81
+published, while a back-order is where you allow a product to be bought that is
  82
+currently out of stock.
  83
+
  84
+
  85
+Shipping
  86
+========
  87
+
  88
+How are shipping charges calculated?
  89
+------------------------------------
  90
+
  91
+There are lots of options and variations here.  Shipping methods and their
  92
+associated charges can take a variety of forms, including:
  93
+
  94
+* A charge based on the weight of the basket
  95
+* Charging a pre-order and pre-item charge
  96
+* Having free shipping for orders above a given threshold
  97
+
  98
+Recipes:
  99
+
  100
+* :doc:`recipes/how_to_configure_shipping`
  101
+
  102
+Which shipping methods are available?
  103
+-------------------------------------
  104
+
  105
+There's often also an issue of which shipping methods are available, as
  106
+this can depend on:
  107
+
  108
+* The shipping address (eg overseas orders have higher charges)
  109
+* The contents of the basket (eg free shipping for downloadable products)
  110
+* Who the user is (eg sales reps get free shipping)
  111
+
  112
+Oscar provides classes for free shipping, fixed charge shipping, pre-order and
  113
+per-product item charges and weight-based charges.  It is provides a mechanism
  114
+for determing which shipping methods are available to the user.
  115
+
  116
+Recipes:
  117
+
  118
+* :doc:`recipes/how_to_configure_shipping`
  119
+
  120
+
  121
+Payment
  122
+=======
  123
+
  124
+How are customers going to pay for orders?
  125
+------------------------------------------
  126
+
  127
+Often a shop will have a single mechanism for taking payment, such
  128
+as integrating with a payment gateway or using PayPal.  However more
  129
+complicated projects will allow users to combine several different payment
  130
+sources such as bankcards, business accounts and giftcards.
  131
+
  132
+Possible payment sources include:
  133
+
  134
+* Bankcard
  135
+* Google checkout
  136
+* PayPal
  137
+* Business account
  138
+* Managed budget
  139
+* Giftcard
  140
+* No upfront payment but send invoices later
  141
+
  142
+The checkout app within django-oscar is suitable flexible that all of these
  143
+methods (and in any combination) is supported.  However, you will need to
  144
+implement the logic for your domain by subclassing the relevant view/util
  145
+classes.
  146
+
  147
+Domain logic is often required to:
  148
+
  149
+* Determine which payment methods are available to an order;
  150
+* Determine if payment can be split across sources and in which combinations;
  151
+* Determine the order in which to take payment
  152
+* Determine how to handle failing payments (this can get complicated when using
  153
+  multiple payment sources to pay for an order).
  154
+
  155
+* :doc:`recipes/how_to_configure_shipping`
  156
+
  157
+When will payment be taken?
  158
+---------------------------
  159
+
  160
+A common pattern is to 'pre-auth' a bankcard at the point of checkout then
  161
+'settle' for the appropriate amouts when the items actually ship.  However,
  162
+sometimes payment is taken up front.  Often you won't have a choice due to
  163
+limitations of the payment partner you need to integrate with.
  164
+
  165
+* Will the customer be debited at point of checkout, or when the items are dispatched?
  166
+* If charging after checkout, when are shipping charges collected?
  167
+* What happens if an order is cancelled after partial payment?
39  docs/source/recipes.rst
Source Rendered
... ...
@@ -1,5 +1,6 @@
  1
+=======
1 2
 Recipes
2  
-============
  3
+=======
3 4
 
4 5
 Recipes are simple guides to solving common problems that occur when creating
5 6
 e-commerce projects.
@@ -7,19 +8,39 @@ e-commerce projects.
7 8
 Customisation
8 9
 -------------
9 10
 
10  
-* :doc:`recipes/how_to_customise_an_app`
11  
-* :doc:`recipes/how_to_customise_models`
12  
-* :doc:`recipes/how_to_override_a_core_class`
  11
+.. toctree::
  12
+    :maxdepth: 1
  13
+
  14
+    recipes/how_to_customise_an_app
  15
+    recipes/how_to_customise_models
  16
+    recipes/how_to_override_a_core_class
  17
+    recipes/how_to_customise_templates
  18
+    recipes/how_to_disable_an_app
13 19
 
14 20
 Catalogue
15 21
 ---------
16 22
 
17  
-* :doc:`recipes/how_to_create_categories`
  23
+.. toctree::
  24
+    :maxdepth: 1
  25
+
  26
+    recipes/how_to_create_categories
  27
+    recipes/how_to_model_your_catalogue
  28
+    recipes/importing_a_catalogue
  29
+
  30
+Pricing, stock and availability
  31
+-------------------------------
18 32
 
19  
-Checkout
  33
+.. toctree::
  34
+    :maxdepth: 1
  35
+
  36
+    recipes/enforcing_stock_rules
  37
+    recipes/how_to_configure_stock_messaging
  38
+
  39
+Shipping
20 40
 --------
21 41
 
22  
-* :doc:`recipes/how_to_configure_shipping`
23  
-* :doc:`recipes/enforcing_stock_rules`
  42
+.. toctree::
  43
+    :maxdepth: 1
  44
+
  45
+    recipes/how_to_configure_shipping
24 46
 
25  
-Lots more to come!
7  docs/source/recipes/how_to_configure_shipping.rst
Source Rendered
@@ -56,9 +56,10 @@ with a custom repository.
56 56
 
57 57
 * ``oscar.apps.shipping.methods.Free``.  No shipping charges.
58 58
 
59  
-* ``oscar.apps.shipping.methods.WeightBased``.  This uses a model ``WeightBand``
60  
-  to provide charges for different weight bands.  By default, the method will calculate
61  
-  the weight of a product by looking for a 'weight' attribute although this can be
  59
+* ``oscar.apps.shipping.methods.WeightBased``.  This is a model-driven method
  60
+  that uses two models: ``WeightBased`` and ``WeightBand`` to provide charges
  61
+  for different weight bands.  By default, the method will calculate the weight
  62
+  of a product by looking for a 'weight' attribute although this can be
62 63
   configured.  
63 64
 
64 65
 * ``oscar.apps.shipping.methods.FixedPrice``.  This simply charges a fixed price for 
3  docs/source/recipes/how_to_configure_stock_messaging.rst
Source Rendered
... ...
@@ -0,0 +1,3 @@
  1
+================================
  2
+How to configure stock messaging
  3
+================================
82  docs/source/recipes/how_to_customise_templates.rst
Source Rendered
... ...
@@ -0,0 +1,82 @@
  1
+==========================
  2
+How to customise templates
  3
+==========================
  4
+
  5
+Assuming you want to use oscar's templates in your project, there are two
  6
+options.  You don't have to though - you could write all your own templates if
  7
+you like.  If you do this, it's probably best to start with a straight copy of
  8
+all of oscar's templates so you know all the files that you need to
  9
+re-implement.
  10
+
  11
+Anyway - here are the two options for customising.
  12
+
  13
+Method 1 - Forking
  14
+------------------
  15
+
  16
+One option is always just to fork the template into your local project so that
  17
+it comes first in the include path.
  18
+
  19
+Say you want to customise ``base.html``.  First you need a project-specific
  20
+templates directory that comes first in the include path.  You can set this up
  21
+as so::
  22
+
  23
+    TEMPLATE_LOADERS = (
  24
+        'django.template.loaders.filesystem.Loader',
  25
+        'django.template.loaders.app_directories.Loader',
  26
+    )
  27
+
  28
+    import os
  29
+    location = lambda x: os.path.join(os.path.dirname(os.path.realpath(__file__)), '..', x)
  30
+    TEMPLATE_DIRS = (
  31
+        location('templates'),
  32
+    )
  33
+
  34
+Next copy oscar's ``base.html`` into your templates directory and customise it
  35
+to suit your needs.
  36
+
  37
+The downsides of this method are that it involves duplicating the file from
  38
+oscar in a way that breaks the link with upstream.  Hence, changes to oscar's
  39
+``base.html`` won't be picked up by your project as you will have your own
  40
+version.
  41
+
  42
+Method 2 - Subclass parent but use same template path
  43
+-----------------------------------------------------
  44
+
  45
+There is a trick you can perform whereby oscar's templates can be accessed via
  46
+two paths.  This is outlined in the `django wiki`_.
  47
+
  48
+.. _`django wiki`: https://code.djangoproject.com/wiki/ExtendingTemplates
  49
+
  50
+This basically means you can have a ``base.html`` in your local templates folder
  51
+that extends oscar's ``base.html`` but only customises the blocks that it needs
  52
+to.
  53
+
  54
+Oscar provides a helper variable to make this easy.  First, set up your
  55
+template configuration as so::
  56
+
  57
+    TEMPLATE_LOADERS = (
  58
+        'django.template.loaders.filesystem.Loader',
  59
+        'django.template.loaders.app_directories.Loader',
  60
+    )
  61
+
  62
+    import os
  63
+    location = lambda x: os.path.join(os.path.dirname(os.path.realpath(__file__)), '..', x)
  64
+    from oscar import OSCAR_PARENT_TEMPLATE_DIR
  65
+    TEMPLATE_DIRS = (
  66
+        location('templates'),
  67
+        OSCAR_PARENT_TEMPLATE_DIR,
  68
+    )
  69
+
  70
+The ``OSCAR_PARENT_TEMPLATE_DIR`` points to the directory above oscar's normal
  71
+templates directory.  This means that ``path/to/oscar/template.html`` can also
  72
+be reached via ``templates/path/to/oscar/template.html``.
  73
+
  74
+Hence to customise ``base.html``, you can have an implementation like::
  75
+
  76
+    # base.html
  77
+    {% extends 'templates/base.html' %}
  78
+
  79
+    ...
  80
+
  81
+No real downsides to this one other than getting your front-end people to
  82
+understand it.
6  docs/source/recipes/how_to_disable_an_app.rst
Source Rendered
... ...
@@ -0,0 +1,6 @@
  1
+=====================
  2
+How to disable an app
  3
+=====================
  4
+
  5
+...
  6
+
10  docs/source/recipes/how_to_model_your_catalogue.rst
Source Rendered
... ...
@@ -0,0 +1,10 @@
  1
+===========================
  2
+How to model your catalogue
  3
+===========================
  4
+
  5
+
  6
+
  7
+Related recipes:
  8
+
  9
+* :doc:`recipes/how_to_customise_an_app`
  10
+* :doc:`recipes/how_to_customise_models`
6  docs/source/recipes/importing_a_catalogue.rst
Source Rendered
... ...
@@ -0,0 +1,6 @@
  1
+=====================
  2
+Importing a catalogue
  3
+=====================
  4
+
  5
+...
  6
+
1  docs/source/reference.rst
Source Rendered
@@ -8,3 +8,4 @@ Contents:
8 8
    :maxdepth: 2
9 9
 
10 10
    reference/settings
  11
+   reference/signals
23  docs/source/reference/signals.rst
Source Rendered
... ...
@@ -0,0 +1,23 @@
  1
+=======
  2
+Signals
  3
+=======
  4
+
  5
+Oscar defined a number of custom signals that provide useful hook-points for
  6
+adding functionality.
  7
+
  8
+order_placed
  9
+------------
  10
+
  11
+.. data:: oscar.apps.order.order_placed
  12
+    :class:
  13
+
  14
+Raised by the :class:`oscar.apps.order.OrderCreator` class when creating an order.
  15
+
  16
+Arguments sent with this signal:
  17
+
  18
+``order``
  19
+    The order created
  20
+
  21
+``user``
  22
+    The user creating the order (not necessarily the user linked to the order
  23
+    instance!)
80  docs/source/take_a_peek.rst
Source Rendered
... ...
@@ -0,0 +1,80 @@
  1
+===========
  2
+Take a peek
  3
+===========
  4
+
  5
+There are several ways to get a feel for Oscar and what it can do.
  6
+
  7
+Browse the sandbox site
  8
+=======================
  9
+
  10
+There is a demo Oscar site, built hourly from HEAD of the master branch (unstable):
  11
+http://sandbox.oscar.tangentlabs.co.uk
  12
+
  13
+It is intended to be a vanilla install of oscar, using the default templates and
  14
+styles.  This is the blank canvas upon which you an build your application.
  15
+
  16
+It only has two customisations on top of oscar's core:
  17
+
  18
+* Two shipping methods are specified so that the shipping method step of
  19
+  checkout is not skipped.  If there is only one shipping method (which is true of core
  20
+  oscar) then the shipping method step is skipped as there is no choice to be
  21
+  made.
  22
+
  23
+* A profile class is specified which defines a few simple fields.  This is to
  24
+  demonstrate the account section of Oscar, which introspects the profile class
  25
+  to build a combined User and Profile form.
  26
+
  27
+Running the sandbox locally
  28
+===========================
  29
+
  30
+It's pretty straightforward to get the sandbox site running locally so you can
  31
+play around with the sourcecode.
  32
+
  33
+Install Oscar and its dependencies within a virtualenv::
  34
+
  35
+    git clone git://github.com/tangentlabs/django-oscar.git
  36
+    cd django-oscar
  37
+    mkvirtualenv oscar
  38
+    python setup.py develop
  39
+    pip install -r requirements.txt
  40
+
  41
+Create a SQLite database and load some sample products and required fixtures::
  42
+
  43
+    cd sandbox
  44
+    ./manage.py syncdb --noinput
  45
+    ./manage.py migrate 
  46
+    ./manage.py oscar_import_catalogue data/books-catalogue.csv 
  47
+    ./manage.py oscar_import_catalogue_images data/books-images.tar.gz 
  48
+    ./manage.py loaddata countries.json fixtures/pages.json 
  49
+
  50
+Now you can browse a sample Oscar site using Django's development server::
  51
+
  52
+    ./manage.py runserver
  53
+
  54
+Note that some things are deliberately not implemented within core Oscar
  55
+as they are domain-specific.  For instance:
  56
+
  57
+* All tax is set to zero
  58
+* The two shipping methods are both free
  59
+* No payment is required to submit an order
  60
+
  61
+I've found a problem!
  62
+---------------------
  63
+
  64
+Please `report them in Github's issue tracker`_.
  65
+
  66
+.. _`report them in Github's issue tracker`: https://github.com/tangentlabs/django-oscar/issues
  67
+
  68
+Browse some real Oscar implementations
  69
+======================================
  70
+
  71
+There are several Oscar implementations in production, although several are B2B
  72
+and hence can't be browsed by the public.  Here's a few public ones to have a
  73
+look at:
  74
+
  75
+* http://www.landmarkonthenet.com - Landmark is part of Tata Group.  This site
  76
+  has a catalogue size of more than 20 million products and integrates with many
  77
+  partners such as Gardners, Ingram, Nielsen, Citibank, Qwikcilver and SAP.
  78
+
  79
+* http://www.dolbeau.ca/ - "Dolbeau delivers weekly limited editions of
  80
+  handcrafted luxury menswear"
3  docs/test_docs.sh
... ...
@@ -0,0 +1,3 @@
  1
+#!/usr/bin/env bash
  2
+make html
  3
+open build/html/index.html &
4  oscar/__init__.py
@@ -3,8 +3,8 @@
3 3
 # Use 'final' as the 4th element to indicate
4 4
 # a full release
5 5
 
6  
-VERSION = (0, 2, 0, 'RC', 2)
7  
-
  6
+VERSION = (0, 2, 0, 'final')
  7
+    
8 8
 def get_short_version():
9 9
     return '%s.%s' % (VERSION[0], VERSION[1])
10 10
 

0 notes on commit 9727c70

Please sign in to comment.
Something went wrong with that request. Please try again.