Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation update.

  • Loading branch information...
commit 9146bf032f39bde089f5ea724ec4bd8388337455 1 parent c034593
@bmihelac authored
View
8 docs/api_default_discounts.rst
@@ -0,0 +1,8 @@
+.. _`default_discounts api`:
+
+=======================
+Bundled discounts types
+=======================
+
+.. automodule:: discount.default_discounts.models
+ :members:
View
7 docs/api_managers.rst
@@ -0,0 +1,7 @@
+========
+Managers
+========
+
+.. autoclass:: discount.models.DiscountBaseManager
+ :members:
+
View
9 docs/api_mixins.rst
@@ -0,0 +1,9 @@
+.. _`mixins api`:
+
+===============
+Discount mixins
+===============
+
+.. automodule:: discount.mixins
+ :members:
+
View
16 docs/api_models.rst
@@ -0,0 +1,16 @@
+======
+Models
+======
+
+DiscountBase
+------------
+
+.. autoclass:: discount.models.DiscountBase
+ :members:
+
+CartDiscountCode
+----------------
+
+.. autoclass:: discount.models.CartDiscountCode
+ :members:
+
View
0  docs/views.rst → docs/api_views.rst
File renamed without changes
View
13 docs/available_discounts.rst
@@ -1,13 +0,0 @@
-=========================
-Available discounts types
-=========================
-
-Cart Item Percent Discount
---------------------------
-
-Adds ``Amount`` percents of price to every eligible cart item.
-
-Cart Item Absolute Discount
----------------------------
-
-Adds ``Amount`` to every eligible cart item.
View
13 docs/changelog.rst
@@ -0,0 +1,13 @@
+===========
+Change Log
+===========
+
+
+0.0.2
+=====
+
+* updated docs
+
+* move default discounts to ``discount.default_discounts`` app
+
+* lot of bugfixes
View
17 docs/conf.py
@@ -16,7 +16,10 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('..'))
+sys.path.append(os.path.abspath('../example'))
+os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
# -- General configuration -----------------------------------------------------
@@ -47,10 +50,14 @@
# |version| and |release|, also used in various other places throughout the
# built documents.
#
-# The short X.Y version.
-version = '0.0.0'
-# The full version, including alpha/beta/rc tags.
-release = '0.0.0'
+try:
+ from discount import __version__
+ # The short X.Y version.
+ version = '.'.join(__version__.split('.')[:2])
+ # The full version, including alpha/beta/rc tags.
+ release = __version__
+except ImportError:
+ version = release = 'dev'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
View
10 docs/contributing.rst
@@ -0,0 +1,10 @@
+=============
+Contributing
+=============
+
+Code guidelines
+================
+
+* As most projects, we try to follow PEP8 as closely as possible
+
+* Most pull requests will be rejected without proper unit testing
View
59 docs/extending_discounts.rst
@@ -1,11 +1,47 @@
-=========================
-Extending discounts types
-=========================
+================
+Custom discounts
+================
-Adding your own discount types is easy.
+Adding custom discount types is easy and can be achived with subclassing
+polymorphic model ``discount.models.DiscountBase``.
-It is achived with subclassing ``discount.models.DiscountBase``
-class and implementing ``process_cart_item`` or ``process_cart`` methods.
+Custom discount types can add fields and override following methods:
+
+* ``get_products`` to filter initial product queryset discount operates on.
+ Overriding this allows to say that discount should be applied only to some
+ categories, for example.
+
+ See also :doc:`filters`
+
+* ``get_extra_cart_item_price_field`` - for adding extra cart item price field
+ to cart items containing eligible products
+
+* ``get_extra_cart_price_field`` - for adding extra cart price field to cart
+
+Design considerations
+---------------------
+
+While django-shop-discount app comes with few bundled discount types, it does
+not asume how specific shop is organized or how discount logic should work.
+
+Typical discounts organization can set base constrains in base discount class
+and specifing constrains in subclasses.
+
+For example::
+
+ class SiteBaseDiscount(DiscountBase):
+ categories = models.ManyToManyField('myshop.Category',
+ help_text=_('Limit discount to selected categories')
+
+ def get_products():
+ qs = super(SiteBaseDiscount, self).get_products()
+ # code that excludes products that does not belong to self.categories
+ return qs
+
+ class CartItemPercentDiscount(SiteBaseDiscount, mixins.CartItemPercentDiscountMixin):
+ pass
+
+See :doc:`api_mixins`.
Example
-------
@@ -24,14 +60,13 @@ Add this model::
amount = models.DecimalField(_('Amount'), max_digits=5, decimal_places=2)
num_items = models.IntegerField(_('Minimum number of items'))
- def process_cart_item(self, cart_item):
+ def get_extra_cart_item_price_field(self, cart_item):
if (cart_item.quantity >= self.num_items and
self.is_eligible_product(cart_item.product, cart_item.cart)):
amount = (self.amount/100) * cart_item.line_subtotal
- to_append = (self.get_name(), amount)
- cart_item.extra_price_fields.append(to_append)
+ return (self.get_name(), amount,)
-Given that you registered ``BulkDiscount`` to django admin, editor would be able
-to set bulk discounts.
+Given that you registered ``BulkDiscount`` with django admin,
+site administrator would be able to set bulk discounts.
-This code is implemented in :doc:`example_app`.
+See this discount in action in :doc:`example_app`.
View
42 docs/filters.rst
@@ -2,31 +2,31 @@
Filters
=======
-Example of implementing filtering products by category in DiscountBase:::
+Filters are ``dict`` or ``callable`` types that, when registered with
+discount class(es) influences which products are eligible for this
+discount.
- def category_product_filter(discount, queryset):
- """
- Allow discount type to be filtered by category.
- """
- if not discount.categories.count():
- return queryset
- ids = [c.id for c in discount.categories.all()]
- return queryset.filter(models.Q( Book___categories__id__in=ids))
+Filters as dict
+---------------
- DiscountBase.register_product_filter(category_product_filter)
+Product queryset is filtered with field lookups defined in dict::
+ filt = {'unit_price__gt': 10}
+ # only products with unit_price > 10 are eligible
+ DiscountBase.register_product_filter(filt)
- #add categories field to BulkDiscount
- BulkDiscount.add_to_class('categories',
- models.ManyToManyField(Category,
- verbose_name=_('Categories'),
- blank=True,
- null=True,
- help_text=_('Limit discount to selected categories')
- ))
+Filters as callable
+-------------------
-This would allow editor to select to what categories of products all discount
-types applies.
+Callable is called with two arguments:
-This code is implemented in :doc:`example_app`.
+* discount model
+* product queryset
+
+::
+ def filt(discount, qs):
+ # only product names as discount are eligible
+ return(qs.filter(name=discount.name))
+
+ DiscountBase.register_product_filter(filt)
View
53 docs/getting_started.rst
@@ -0,0 +1,53 @@
+===============
+Getting started
+===============
+
+Configuration
+-------------
+
+1. Add `discount` to INSTALLED_APPS::
+
+ INSTALLED_APPS = (
+ 'shop', # The django SHOP application
+ 'discount',
+ )
+
+2. Add `DiscountCartModifier` to `SHOP_CART_MODIFIERS`::
+
+ SHOP_CART_MODIFIERS = [
+ 'discount.cart_modifiers.DiscountCartModifier',
+ ]
+
+``DiscountCartModifier`` is implemented as `django-shop` cart modifier.
+It will be called on every `Cart` update call.
+
+``DiscountCartModifier`` loops through active discounts adding extra cart
+or extra cart item field when given discount is eligible:
+
+Active discounts are discounts with set ``active`` flag and within date range
+specified with Valid from - Valid to.
+
+If ``code`` for the discount is set, user have to enter this `code` to
+activate discount.
+
+3. Include django-shop-discount urls::
+
+ urlpatterns = patterns('',
+ (r'^discount/', include('discount.urls')),
+ )
+
+This will include views for entering and removing discount code.
+
+Quick start
+-----------
+
+django-shop-discount includes few bundled discount types.
+
+To use them, add ``discount.default_discounts`` app to `INSTALLED_APPS`.
+
+Next steps
+----------
+
+* :doc:`Custom discounts<extending_discounts>`
+
+* :doc:`Discount filters<filters>`
View
44 docs/index.rst
@@ -1,18 +1,46 @@
-===============================================
-Welcome to django-shop-discounts documentation!
-===============================================
+============================
+Discount app for django-shop
+============================
-Contents:
+django-shop-discounts aims to be configurable and extendible discount
+app for Django-shop.
+
+Features:
+
+* multiple discount types
+
+* define date ranges when discount is valid
+
+* discount codes (that need to be entered by user for discount to be valid)
+
+* registering filters allow narrowing products discounts may apply to
+ (for example by site, product category, color, etc)
+
+django-shop-discounts is currently considered alpha version.
+
+User Guide
+----------
.. toctree::
:maxdepth: 2
- introduction
installation
- usage
- available_discounts
+ getting_started
extending_discounts
filters
- views
example_app
todo
+ contributing
+ changelog
+
+API documentation
+-----------------
+
+.. toctree::
+ :maxdepth: 2
+
+ api_models
+ api_managers
+ api_views
+ api_mixins
+ api_default_discounts
View
19 docs/installation.rst
@@ -2,21 +2,6 @@
Installation
============
-1. Add `discount` to INSTALLED_APPS::
+::
- INSTALLED_APPS = (
- 'shop', # The django SHOP application
- 'discount',
- )
-
-2. Add `DiscountCartModifier` to `SHOP_CART_MODIFIERS`::
-
- SHOP_CART_MODIFIERS = [
- 'discount.cart_modifiers.DiscountCartModifier',
- ]
-
-3. Include urls:::
-
- urlpatterns = patterns('',
- (r'^discount/', include('discount.urls')),
- )
+ pip install django-shop-discounts
View
19 docs/introduction.rst
@@ -1,19 +0,0 @@
-============
-Introduction
-============
-
-django-shop-discounts aims to be bring configurable and extendible discount
-app for Django-shop.
-
-Current features:
-
-* multiple discount types
-
-* define date ranges when discount is valid
-
-* discount codes (that need to be entered by user for discount to be valid)
-
-* defining filters to allow selecting products to which discounts may apply
- (by product category, color, whatever)
-
-django-shop-discounts is currently considered alpha version.
View
10 docs/todo.rst
@@ -2,12 +2,12 @@
TODO
====
-* handle overlapping discounts
+* number of uses does not work yet (for this to work django-shop should have
+ a way to attach additional data to cart item price fields)
-* discount type for free shipping
+* support for multiple, non reusable discount codes
-* number of uses does not work yet
+* handle overlapping discounts
-* allow different discount codes
+* discount type for free shipping
-* optimize
View
29 docs/usage.rst
@@ -1,29 +0,0 @@
-=====
-Usage
-=====
-
-``DiscountCartModifier`` is django-shop cart modifier. It would be called on
-every cart update call.
-
-``DiscountCartModifier`` loop through active discounts for cart and for for
-discounts with eligible products in cart it may add:
-
-* extra price field for whole cart,
-
-* extra price field for individual cart items
-
-Active discounts
-----------------
-
-Active discounts are discounts with ``active`` flag and within date range
-specified with Valid from - Valid to.
-
-If ``code`` for the discount is set, for dicount to be active Cart object
-should have associated CartDiscountCode with same code.
-
-Eligible products
------------------
-
-Eligible products for discounts are selected based on filters.
-
-See :doc:`filters`.
Please sign in to comment.
Something went wrong with that request. Please try again.