Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Updated documentation - still not complete but much better
  • Loading branch information
codeinthehole committed Jun 1, 2012
1 parent fe4bcd5 commit 9727c70
Show file tree
Hide file tree
Showing 20 changed files with 681 additions and 206 deletions.
20 changes: 16 additions & 4 deletions README.rst
Expand Up @@ -10,19 +10,27 @@ core functionality can be customised to suit the needs of your project. This
allows it to handle a wide range of e-commerce requirements, from large-scale B2C
sites to complex B2B sites rich in domain-specific business logic.

Oscar is used in production by:
Case studies
------------

* Tata - http://www.landmarkonthenet.com
* Carlsberg - Their global "We deliver more" platform is powered by Oscar.
Oscar is still in active development, but is used in production by a range of
companies, from large multinationals to small, boutique stores:

* Tata Group - http://www.landmarkonthenet.com
* Carlsberg - Their global "We Deliver More" platform is powered by Oscar (but
is a B2B site so it not browsable by the public).
* Dolbeau - http://www.dolbeau.ca/
* The UK Labour party
* The UK Labour party - http://shop.labour.org.uk (will be live in early June)

Many more on the way.

This README is just a stub - see the following links for more details
information:

* `Official homepage`_
* `Demo site`_ (experimental)
* `Documentation`_ on `readthedocs.org`_
* `Google Group`_ - the mailing list is django-oscar@googlegroups.com
* `Continuous integration homepage`_ on `travis-ci.org`_
* `Twitter account for news and updates`_
* `Twitter account of all commits`_
Expand All @@ -37,10 +45,14 @@ information:
.. _`travis-ci.org`: http://travis-ci.org/
.. _`Twitter account for news and updates`: https://twitter.com/#!/django_oscar
.. _`Twitter account of all commits`: https://twitter.com/#!/oscar_django
.. _`Google Group`: https://groups.google.com/forum/?fromgroups#!forum/django-oscar

Oscar was written by `David Winterbottom`_ (`@codeinthehole`_) and is developed
and maintained by `Tangent Labs`_, a London-based digital agency.

Oscar is released under the permissive `New BSD license`_.

.. _`David Winterbottom`: http://codeinthehole.com
.. _`@codeinthehole`: https://twitter.com/codeinthehole
.. _`Tangent Labs`: http://www.tangentlabs.co.uk
.. _`New BSD license`: https://github.com/tangentlabs/django-oscar/blob/master/LICENSE
16 changes: 0 additions & 16 deletions docs/source/components.rst

This file was deleted.

72 changes: 63 additions & 9 deletions docs/source/contributing.rst
Expand Up @@ -2,15 +2,69 @@
Contributing
============

* New features should be discussed on the mailing list (or in the meetings) before serious work starts
* Pull requests will be rejected if sufficient tests aren't provided
* Please update the documentation when altering behaviour or introducing new features
Some ground rules:

Contents:
* To avoid disappointment, new features should be discussed on the mailing list
(django-oscar@googlegroups.com) before serious work starts.

.. toctree::
:maxdepth: 2
* Pull requests will be rejected if sufficient tests aren't provided.

contributing/installation
contributing/testing
contributing/conventions
* Please update the documentation when altering behaviour or introducing new features.

* Follow the conventions (see below).

Installation
============

From zero to tests passing in 2 minutes (most of which is PIL installing)::

git clone git@github.com:<username>/django-oscar.git
cd django-oscar
mkvirtualenv oscar
./setup.py develop
pip install -r requirements.txt
./run_tests.py

Writing docs
============

There's a helper script for building the docs locally::

cd docs
./test_docs.sh

Conventions
===========

General
-------

* PEP8 everywhere while remaining sensible

URLs
----

* List pages should use plurals, eg ``/products/``, ``/notifications/``

* Detail pages should simply be a PK/slug on top of the list page, eg
``/products/the-bible/``, ``/notifications/1/``

* Create pages should have 'create' as the final path segment, eg
``/dashboard/notifications/create/``

* Update pages are sometimes the same as detail pages (ie when in the
dashboard). In those cases, just use the detail convention, eg
``/dashboard/notifications/3/``. If there is a distinction between the detail
page and the update page, use ``/dashboard/notifications/3/update/``.

* Delete pages, eg /dashboard/notifications/3/delete/

View class names
----------------

Classes should be named according to::

'%s%sView' % (class_name, verb)

For example, ``ProductUpdateView``, ``OfferCreateView`` and
``PromotionDeleteView``. This doesn't fit all situations but it's a good basis.
File renamed without changes.
197 changes: 146 additions & 51 deletions docs/source/getting_started.rst
@@ -1,76 +1,171 @@
===============
Getting started
============================
Start building your own shop
============================

For simplicity, let's assume you're building a new e-commerce project from
scratch and have decided to use Oscar. Let's call this shop 'frobshop'

.. tip::

You can always review the set-up of the `Sandbox site`_ in case you have
trouble following the below instructions.

.. _`Sandbox site`: https://github.com/tangentlabs/django-oscar/tree/releases/0.2/sandbox

Install by hand
===============

Install using::
Install oscar (which will install Django as a dependency), then create the
project::

pip install django-oscar
django-admin.py startproject frobshop

This will create a folder ``frobshop`` for your project.

Settings
--------

Now edit your settings file ``frobshop.frobshop.settings.py`` to specify a
database (we use sqlite for simplicity)::

DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': 'db.sqlite3',
'USER': '',
'PASSWORD': '',
'HOST': '',
'PORT': '',
}
}

then add ``oscar.apps.basket.middleware.BasketMiddleware`` to ``MIDDLEWARE_CLASSES``, and
set ``TEMPLATE_CONTEXT_PROCESSORS`` to::

TEMPLATE_CONTEXT_PROCESSORS = (
"django.contrib.auth.context_processors.auth",
"django.core.context_processors.request",
"django.core.context_processors.debug",
"django.core.context_processors.i18n",
"django.core.context_processors.media",
"django.core.context_processors.static",
"django.contrib.messages.context_processors.messages",
'oscar.apps.search.context_processors.search_form',
'oscar.apps.promotions.context_processors.promotions',
'oscar.apps.checkout.context_processors.checkout',
'oscar.core.context_processors.metadata',
)

Next, modify ``INSTALLED_APPS`` to be a list, add ``South`` and append Oscar's core apps::

then add::
from oscar import get_core_apps
INSTALLED_APPS = [
'django.contrib.auth',
...
'south',
] + get_core_apps()

'oscar.apps.basket.middleware.BasketMiddleware'
and set your auth backends to::

to ``MIDDLEWARE_CLASSES``, and::
AUTHENTICATION_BACKENDS = (
'oscar.apps.customer.auth_backends.Emailbackend',
'django.contrib.auth.backends.ModelBackend',
)

'oscar.apps.promotions.context_processors.promotions',
'oscar.apps.checkout.context_processors.checkout',
to allow customers to sign in using an email address rather than a username.

to ``TEMPLATE_CONTEXT_PROCESSORS``. Next, add the following apps
to your ``INSTALLED_APPS``::
Oscar currently uses Haystack for search so you need to specify::

'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',
HAYSTACK_SITECONF = 'oscar.search_sites'
HAYSTACK_SEARCH_ENGINE = 'dummy'

Add::
The last addition to the settings file is to import all of Oscar's default settings::

from oscar.defaults import *

to your ``settings`` module and run::
URLs
----

Alter your ``frobshop/urls.py`` to include Oscar's URLs::

from django.conf.urls import patterns, include, url
from oscar.app import shop

urlpatterns = ('',
(r'', include(shop.urls))
)

Database
--------

Then create the database and the shop should be browsable::

python manage.py syncdb --noinput
python manage.py migrate

You should now have a running Oscar install that you can browse.


Install using Tangent's boilerplate django project
==================================================

The easiest way to get started is to use Tangent's `template django project`_
although it is tailored to an Agency structure which may not suit everyone.

.. `template django project`: https://github.com/tangentlabs/tangent-django-boilerplate
Set up a virtualenv, and create a new project using the ``startproject``
management command::

mkvirtualenv frobshop
pip install Django
django-admin.py startproject frobshop \
--template=https://github.com/tangentlabs/tangent-django-boilerplate/zipball/master

python manage.py syncdb
This will create a folder ``frobshop`` which is an entire templated project that
follows Tangent's conventions. The structure is:

to create the database tables.
frobshop/
docs/
www/
conf/
deploy/
public/
static/
templates/
manage.py
settings.py
settings_test.py
urls.py
urls_oscar.py
README.rst
fabconfig.py
fabfile.py
deploy-to-test.sh
deploy-to-stage.sh
deploy-to-prod.sh

Replace a few files with Oscar-specific versions::

Demo shop
---------
mv frobshop/www/urls{_oscar,}.py
mv frobshop/www/deploy/requirements{_oscar,}.py
mv frobshop/www/conf/default{_oscar,}.py

A demo shop is in preparation at the moment and will be available soon.
Install dependencies::

Real shop
---------
cd frobshop/www
pip install -r deploy/requirements.txt

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:
Create database::

* 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?
python manage.py syncdb -noinput
python manage.py migrate

Much of the documentation for oscar is organised as recipes that explain
how to solve questions such as those above:
And that should be it.

* :doc:`recipes/how_to_customise_an_app`
* :doc:`recipes/how_to_customise_models`
* :doc:`recipes/how_to_override_a_core_class`
Next steps
==========

The next step is to implement the business logic of your domain on top of
Oscar.

0 comments on commit 9727c70

Please sign in to comment.