Manual merge branch 'feature/betterdocs'

Conflicts:
	docs/source/recipes.rst

CONTRIBUTING.rst

@@ -180,6 +180,31 @@ There's a helper script for building the docs locally::
     cd docs
     ./test_docs.sh
 
+The actual docs are in ``/docs/source``. This directory structure is a
+simplified version of what Django does.
+
+* ``internals/`` contains everything related to Oscar itself, e.g. contributing
+  guidelines or design philosophies.
+* ``ref/`` is the reference documentation, esp. consisting of
+* ``ref/apps/`` which should be a guide to each Oscar core app, explaining it's
+  function, the main models, how it relates to the other apps, etc.
+* ``topics/`` will contain "meta" articles, explaining how things tie together
+  over several apps, or how Oscar can be combined with other solutions.
+* ``howto/`` contains tutorial-style descriptions on how to solve a certain
+  problem. Ideally, those will be kept to a minimum; as the other docs should
+  be understandable enough that necessary steps to achieve a certain goal are
+  obvious.
+* ``_old/`` contains legacy documents that have not been moved into the new
+  structure. Please help get rid of those!
+
+``/index.rst`` is designed as the entry point, and diverges from above
+structure to make the documentation more approachable. Other ``index.rst``
+files should only be created if there's too many files to list them all.
+E.g. ``/index.rst`` directly links to all files in ``topics/`` and
+``internals/``, but there's an ``index.rst`` both for the files in ``howto/``
+and ``ref/apps/``.
+
+
 Conventions
 ===========
 

docs/source/_draft/contributing/installation.rst

@@ -1,101 +0,0 @@
-================================
-Installing Oscar for development
-================================
-
-Note that these instructions assume you are developing on Ubuntu.
-
-Virtual environment
--------------------
-
-Set up ``pip`` and ``virtualenv`` if you haven't already done so::
-
-    sudo apt-get install python-setuptools
-    sudo easy_install pip
-    sudo pip install virtualenv virtualenvwrapper
-    echo "source `which virtualenvwrapper`" >> ~/.bashrc
-
-Reload bash to add the virtualenvwrapper commands to your path::
-
-    . ~/.bashrc
-
-Create a virtualenv for development::
-
-    mkvirtualenv --no-site-packages oscar
-    workon oscar
-
-Forking Oscar
--------------
-
-Sign in to GitHub, navigate to https://github.com/tangentlabs/django-oscar and click "Fork".  This will create a 
-copy of the repository in your account.
-
-Now clone the remote repository to your machine::
-
-    cd workspace
-    git clone git@github.com:username/django-oscar.git
-    
-See the GitHub guide to forking for more details (http://help.github.com/fork-a-repo/).      
-
-Install Oscar and dependencies
-------------------------------
-
-Install Django and the packages from the requirements file, which aren't essential but are useful
-for testing and development::
-
-    pip install Django
-    pip install -r requirements-dev.txt
-
-Install Oscar in development mode within your virtualenv::
-
-    cd django-oscar
-    python setup.py develop
-
-Note: In case of gcc crashing and complaining in-between installation process,
-make sure you have appropriate ``-devel`` packages installed (i.e., ``mysql-devel``) in
-your system.
-
-Now create a ``settings_local.py`` file which contains details of your local database
-that you want to use for development.  At a minimum, this needs to define the ``DATABASES`` tuple.
-
-Developing
-----------
-
-Developing Oscar normally involves working on a Django project which uses Oscar
-as a installed app.  There are several such projects within the ``examples`` folder:
-
-* The ``vanilla`` project does not customise Oscar at all and uses everything in its 
-  default format.  It represents a blank canvas for an e-commerce shop.
-* The ``demo`` project does customise Oscar, and is intended to demonstrate the range 
-  of features in Oscar.   
-
-Each example shop has its own ``manage.py`` executable which you can use to create 
-your database::
-
-    ./manage.py syncdb
- 
-Install sample data
--------------------
-
-Oscar ships with sample data for a simple bookshop.  Load the product data and images using the
-following commands::
-
-    cd examples/vanilla
-    ./manage.py import_catalogue ../sample-data/books.csv
-    ./manage.py import_images ../sample-data/book-images/
-    ./manage.py update_index 
- 
- 
-Helper scripts
--------------- 
-    
-There is a shortcut script for dropping all of a projects's apps and rerunning ``syncdb`` in
-the `examples` folder - you need to specify which project to act on::
-
-    ./recreate_project_tables.sh vanilla
-    
-There is a similar script for running tests::
-
-    ./run_tests.sh vanilla
-    
-This specifies a sqlite3 database to use for testing and filters out the useless output.
-

docs/source/_draft/contributing/testing.rst

@@ -1,10 +0,0 @@
-=======
-Testing
-=======
-
-There is a similar script for running tests::
-
-    cd examples
-    ./run_tests.sh vanilla
-    
-This specifies a sqlite3 database to use for testing and filters out the useless output.

docs/source/_draft/draft.rst

@@ -1,35 +0,0 @@
-Quick start
-===========
-
-We can do this quickly.  Create a virtualenv using virtualenvwrapper and
-install Django and django-oscar::
-
-    mkvirtualenv --no-site-packages vanilla
-    pip install Django django-oscar
-
-Take a copy of the sample settings file, found at::
-
-    https://github.com/tangentlabs/django-oscar/blob/master/examples/vanilla/settings_quickstart.py
-
-Import the sample products and images::
-
-    wget https://github.com/tangentlabs/django-oscar/blob/master/examples/sample-data/books-catalogue.csv
-    python manage.py import_catalogue books-catalogue.csv
-
-    wget https://github.com/tangentlabs/django-oscar/blob/master/examples/sample-data/book-images.tar.gz
-    python manage.py import_images book-images.tar.gz
-
-And there you have it: a fully functional e-commerce site with a product range of 100 popular books.
-
-
-
-
-
-For
-instance, if every product in your shop has an associated video, then
-Oscar lets you add such a field to your core product model.  You don't
-have to model your domain logic using the `Entity-Attribute-Value`_ pattern or
-other such meta-nastiness - your core models should reflect the specifics of
-your domain.
-
-.. _`Entity-Attribute-Value`: http://en.wikipedia.org/wiki/Entity%E2%80%93attribute%E2%80%93value_model

docs/source/_draft/getting_started/create_product_catalogue.rst

@@ -1,4 +0,0 @@
-Create product catalogue
-========================
-
-...

docs/source/_draft/getting_started/customising_models.rst

@@ -1,4 +0,0 @@
-Customising models
-==================
-
-...

docs/source/_draft/getting_started/installation.rst

@@ -1,116 +0,0 @@
-================
-Installing Oscar
-================
-
-Environment
------------
-
-This section is optional but recommended.
-
-Install pip and virtualenv (if you haven't already)::
-
-    sudo apt-get install python-setuptools
-    sudo easy_install pip
-    sudo pip install virtualenv virtualenvwrapper
-    echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc
-
-Create a new virtual env::
-
-    mkvirtualenv --no-site-packages $PROJECTNAME
-
-A nice extension now is to edit your ``~/.virtualenv/$PROJECTNAME/bin/postactivate`` file to contain::
-
-    cd ~/path/to/my/workspace/$PROJECTNAME
-
-so that you can simply type ``workon $PROJECTNAME`` to jump into your project folder with the virtual
-environment set-up.
-
-Installation
-------------
-
-Install Oscar and its dependencies::
-
-    pip install -e git+git://github.com/tangentlabs/django-oscar.git#egg=django-oscar
-
-You will also need to install the appropriate python module for your database of choice.
-If you are using MySQL, then run the following::
-
-    pip install MySQL-python
-
-Also, depending on your search backend for haystack, you'll need to install further
-packages::
-
-    pip install pysolr
-
-Now create the project::
-
-    cd /path/to/my/workspace
-    django-admin.py startproject $PROJECTNAME
-
-Configure ``settings.py``
--------------------------
-
-* Add ``'django.middleware.transaction.TransactionMiddleware'`` to your ``MIDDLEWARE_CLASSES`` tuple, making
-  sure it comes AFTER ``'django.contrib.auth.middleware.AuthenticationMiddleware'``.
-
-* Add the following to your `INSTALLED_APPS`::
-
-    'haystack',
-    'oscar',
-    'oscar.apps.analytics',
-    'oscar.apps.discount',
-    'oscar.apps.order',
-    'oscar.apps.checkout',
-    'oscar.apps.shipping',
-    'oscar.apps.order_management',
-    'oscar.apps.product',
-    'oscar.apps.basket',
-    'oscar.apps.payment',
-    'oscar.apps.offer',
-    'oscar.apps.address',
-    'oscar.apps.partner',
-    'oscar.apps.image',
-    'oscar.apps.customer',
-    'oscar.apps.promotions',
-    'oscar.apps.reports',
-    'oscar.apps.search',
-    'oscar.apps.catalogue_import',
-
-
-* Add these to ``TEMPLATE_CONTECT_PROCESSORS``::
-
-    'oscar.apps.search.context_processors.search_form',
-    'oscar.apps.promotions.context_processors.promotions',
-    'oscar.apps.promotions.context_processors.merchandising_blocks',
-
-* Import default settings::
-
-    from oscar.defaults import *
-
-* If using Solr, configure it::
-
-    HAYSTACK_SITECONF = 'oscar.search_sites'
-    HAYSTACK_SEARCH_ENGINE = 'solr'
-    HAYSTACK_SOLR_URL = 'http://127.0.0.1:8080/solr'
-    HAYSTACK_INCLUDE_SPELLING = True
-
-Now fill in the normal settings (not related to Oscar) within ``settings.py`` - e.g., ``DATABASES``, ``TIME_ZONE`` etc
-
-A vanilla install of Oscar is now ready, you could now finish the process by running::
-
-    ./manage.py syncdb
-
-However, in reality you will need to start extending the models to match your domain.  It's best to do
-this before creating your initial schema.
-
-Configure URLs
---------------
-
-Oscar comes with a number of urls and views out of the box.  These are
-recommendations rather than a requirement, but you easily use them in your
-e-commerce site by adding the Oscar urls to your projects local ``urls.py``::
-
-    (r'^', include('oscar.urls')),
-
-This will bring in all of Oscar's defined urls. Of course you can pull in the
-urls for the individual apps if you prefer or simply define your own

docs/source/_draft/getting_started/overriding_core_classes.rst

@@ -1,24 +0,0 @@
-Customising core classes
-========================
-
-As much as possible, Oscar's core functionality is implemented in classes that are dynamically loaded
-based on the values in ``settings.py``.  This means that any class can be extended and overridden
-in your project to customise its behaviour.
-
-To customise a single class, the process is as follows:
-
-1.  Create a new app within your project with the same name as the app you are customising from oscar.  
-    For example, if you want to change something from ``oscar.checkout.forms``, then create an app
-    ``myshop.checkout`` and add a module ``forms.py``.  
-
-2.  In this new module, create a new version of the class you want to customise.  This is usually done
-    by importing the core class with a new name and then extended/overriding its functionality::
-
-        from oscar.checkout.forms import ShippingAddressForm as CoreShippingAddressForm
-        
-        class ShippingAddressForm(CoreShippingAddressForm):
-            
-            # Customisation here
-            pass
-
-3.  Add your new app to ``settings.py``, replacing its counterpart from Oscar's core.

docs/source/_draft/inventory_management.rst

@@ -1,3 +0,0 @@
-Inventory management REST services
-==================================
-

docs/source/_draft/order_management.rst

@@ -1,62 +0,0 @@
-Order management REST services
-==============================
-
-Supported methods and resources:
-
-**Retrieve list of orders:**::
-
-    GET /orders/
-
-Filters:
-
-* ``after=2010-10-01`` - Return all orders placed after 2010-10-01
-* ``before=2010-10-31`` - Return all orders placed before 2010-10-31
-
-**Retrieve a summary of an order with number 123 (not id)**::
-
-    GET /order/123/
-
-**Retrieve a list of batches**::
-
-    GET /order/123/batches/
-
-**Retrieve a summary of batch**::
-
-    GET /order/123/batch/34/
-
-**Retrieve a list of lines**::
-
-    GET /order/123/batch/34/lines/ [just lines within batch 34, part of order 123]
-    
-    GET /order/123/lines/ [all lines within order 123]
-    
-    GET /lines/ [all lines]
-
-Filters:
-
-* ``at_shipping_status`` - Returns lines at the specified shipping status (use the code)
-
-* ``at_payment_status`` - Returns lines at the specified payment status (use the code)
-
-* ``partner`` - Returns lines fulfilled by a particular partner
-
-**Retrieve a summary of a lines with ids 100,101,102**::
-
-    GET /order/123/batch/34/line/100;101;102`` 
-
-    GET /order/123/line/100;101;102`` 
-
-**Update shipping status of an order line**::
-
-    POST /order/123/batch/34/line/100/ 
-
-    POST /order/123/lines/ 
-
-Request:
-
-``{'shipping_status': 'acknowledged'}`` - Update every item in line
-
-``{'shipping_status': {'acknowledged': 10, 'cancelled': 1}}`` - Fine-grained control
-
-
-

docs/source/_draft/stock_management.rst

@@ -1,3 +0,0 @@
-Stock management REST services
-==============================
-

docs/source/_draft/web_services.rst

@@ -1,12 +0,0 @@
-Web services
-============
-
-Oscar exposes three different RESTful webservices for administration:
-
-.. toctree::
-   :maxdepth: 2
-
-   web_services/order_management
-   web_services/stock_management
-   web_services/inventory_management
-

docs/source/contributing.rst

@@ -1 +0,0 @@
-../../CONTRIBUTING.rst

docs/source/howto/index.rst

@@ -0,0 +1,81 @@
+=======
+Recipes
+=======
+
+Recipes are simple guides to solving common problems that occur when creating
+e-commerce projects.
+
+Customisation
+-------------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_customise_an_app
+    how_to_customise_models
+    how_to_override_a_core_class
+    how_to_customise_templates
+    how_to_disable_an_app
+    how_to_change_a_url
+    how_to_configure_the_dashboard_navigation
+
+Catalogue
+---------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_create_categories
+    how_to_model_your_catalogue
+    importing_a_catalogue
+
+Pricing, stock and availability
+-------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    enforcing_stock_rules
+    how_to_configure_stock_messaging
+
+Payment
+-------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_integrate_payment
+    how_to_apply_tax_exemptions
+
+Shipping
+--------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_configure_shipping
+
+Offers
+------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_create_a_custom_range
+    how_to_create_a_custom_condition
+
+Appearance
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_handle_statics
+
+Contributing
+------------
+
+.. toctree::
+    :maxdepth: 1
+
+    how_do_i_translate_oscar

docs/source/index.rst

@@ -1,7 +1,3 @@
-.. 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.
-
 .. image:: http://img692.imageshack.us/img692/6498/logovf.png
 
 ===================================
@@ -62,22 +58,37 @@ ipads.  The `source is on GitHub`_ - contributions welcome.
 .. _`Tangent Labs`: http://www.tangentlabs.co.uk
 .. _`source is on GitHub`: https://github.com/tangentlabs/django-oscar
 
+Table of contents
+=================
+
+First steps
+-----------
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   take_a_peek
-   getting_started
-   key_questions
-   recipes
-   getting_help
-   design_decisions
-   reference
-   contributing
+   internals/take_a_peek
+   internals/getting_started
+   internals/getting_help
+   topics/key_questions
 
-Indices and tables
-==================
+Using Oscar
+-----------
+All you need to start developing apps with Oscar.
+
+.. toctree::
+   :maxdepth: 1
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   howto/index
+   ref/apps/index
+   ref/settings
+   ref/signals
+
+The Oscar open-source project
+-----------------------------
+Learn about the ideas behind Oscar and how you can contribute.
+
+.. toctree::
+   :maxdepth: 1
 
+   internals/contributing
+   internals/design_decisions

docs/source/internals/contributing.rst

@@ -0,0 +1 @@
+../../../CONTRIBUTING.rst

docs/source/getting_help.rst → docs/source/internals/getting_help.rst

@@ -10,14 +10,6 @@ the solution as a recipe.
 
 .. _`Google Groups archive`: https://groups.google.com/forum/?fromgroups#!forum/django-oscar
 
-Solutions to common problems
-----------------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    problems/my_model_customisations_arent_picked_up
-
 If you find a bug, please report it in the `GitHub issue tracker`_
 
 .. _`GitHub issue tracker`: https://github.com/tangentlabs/django-oscar/issues

docs/source/recipes.rst

@@ -1,81 +0,0 @@
-=======
-Recipes
-=======
-
-Recipes are simple guides to solving common problems that occur when creating
-e-commerce projects.
-
-Customisation
--------------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_to_customise_an_app
-    recipes/how_to_customise_models
-    recipes/how_to_override_a_core_class
-    recipes/how_to_customise_templates
-    recipes/how_to_disable_an_app
-    recipes/how_to_change_a_url
-    recipes/how_to_configure_the_dashboard_navigation
-
-Catalogue
----------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_to_create_categories
-    recipes/how_to_model_your_catalogue
-    recipes/importing_a_catalogue
-
-Pricing, stock and availability
--------------------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/enforcing_stock_rules
-    recipes/how_to_configure_stock_messaging
-
-Payment
--------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_to_integrate_payment
-    recipes/how_to_apply_tax_exemptions
-
-Shipping
---------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_to_configure_shipping
-
-Offers
-------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_to_create_a_custom_range
-    recipes/how_to_create_a_custom_condition
-
-Appearance
-----------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_to_handle_statics
-
-Contributing
-------------
-
-.. toctree::
-    :maxdepth: 1
-
-    recipes/how_do_i_translate_oscar

docs/source/ref/apps/index.rst

@@ -0,0 +1,24 @@
+===============
+Oscar Core Apps
+===============
+
+Oscar is split up in multiple, mostly independent apps.
+
+.. toctree::
+   :maxdepth: 1
+
+   address
+   analytics
+   basket
+   catalogue
+   checkout
+   customer
+   dashboard
+   offer
+   order
+   partner
+   payment
+   promotions
+   search
+   shipping
+   voucher

docs/source/reference.rst

@@ -1,11 +0,0 @@
-=========
-Reference
-=========
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   reference/settings
-   reference/signals

docs/source/key_questions.rst → docs/source/topics/key_questions.rst

@@ -30,8 +30,8 @@ need to capture the attributes of your product types within your models.  Oscar
 divides products into 'product classes' which each have their own set of
 attributes.  
 
-* :doc:`recipes/how_to_model_your_catalogue`
-* :doc:`recipes/importing_a_catalogue`
+* :doc:`/howto/how_to_model_your_catalogue`
+* :doc:`/howto/importing_a_catalogue`
 
 How is your catalogue organised?
 --------------------------------
@@ -46,9 +46,9 @@ theme, by product type).  Other questions to consider:
 * Can a category sit in more than one place within the tree?  (e.g., a "children's fiction" category
   might sit beneath "children's books" and "fiction").
 
-* :doc:`recipes/how_to_customise_an_app`
-* :doc:`recipes/how_to_customise_models`
-* :doc:`recipes/how_to_override_a_core_class`
+* :doc:`/howto/how_to_customise_an_app`
+* :doc:`/howto/how_to_customise_models`
+* :doc:`/howto/how_to_override_a_core_class`
 
 How are products managed?
 -------------------------
@@ -57,7 +57,7 @@ Is the catalogue managed by a admin using a dashboard, or though an automated
 process, such as processing feeds from a fulfillment system?  Where are your
 product images going to be served from?
 
-* :doc:`recipes/how_to_disable_an_app`
+* :doc:`/howto/how_to_disable_an_app`
 
 
 Pricing, stock and availability
@@ -72,7 +72,7 @@ What availability messages are shown to customers?
 Based on the stock information from a fulfillment partner, what messaging should be
 displayed on the site?  
 
-* :doc:`recipes/how_to_configure_stock_messaging`
+* :doc:`/howto/how_to_configure_stock_messaging`
 
 Do you allow pre- and back-orders
 ---------------------------------
@@ -97,7 +97,7 @@ associated charges can take a variety of forms, including:
 
 Recipes:
 
-* :doc:`recipes/how_to_configure_shipping`
+* :doc:`/howto/how_to_configure_shipping`
 
 Which shipping methods are available?
 -------------------------------------
@@ -115,7 +115,7 @@ for determining which shipping methods are available to the user.
 
 Recipes:
 
-* :doc:`recipes/how_to_configure_shipping`
+* :doc:`/howto/how_to_configure_shipping`
 
 
 Payment
@@ -152,7 +152,7 @@ Domain logic is often required to:
 * Determine how to handle failing payments (this can get complicated when using
   multiple payment sources to pay for an order).
 
-* :doc:`recipes/how_to_configure_shipping`
+* :doc:`/howto/how_to_configure_shipping`
 
 When will payment be taken?
 ---------------------------