Browse files

Improve README

* Add screenshots
* Better installation instructions
  • Loading branch information...
1 parent 6eda984 commit 6cb7dc76ef8c09312822f438d9a6d991fec61c70 @codeinthehole codeinthehole committed Jan 25, 2013
@@ -1,63 +1,67 @@
-Store Extension for the Oscar Ecommerce Platform
+Oscar stores
-.. image::
- :target:!/elbaschid/django-oscar
+This is an extension for django-oscar_ that adds support for stores. It
-This project is currently a work in progress. It works
-for the most part but there's most likely unfixed issues in there.
-If you feel the need to try it out, use with care.
-Feedback welcome :)
+.. _django-oscar:
+* A store locator page using Google maps for geocoding. It also supports using
+ the browser's location to show the nearest stores.
+* Store detail pages including opening hours
+* Store groups
+* A dashboard for managing stores
+.. image::
+ :target:
+.. image::
+ :target:
-This package is an extension to `django-oscar`_ that provides an interface to
-add and update store locations as well as grouping them together. An address, a
-geographical location and an arbitrary number of opening times can be specified
-for each store location. Creating and editing of stores is done in the
-dashboard and requires the corresponding permission.
+GeoDjango_ is used so a spatial database is required. We recommend PostGIS.
+Django's docs include some `installation instructions`_.
-All stores are displayed on the website in an overview map followed
-by a listing of each store ordered by store groups. For each store,
-the address and opening times are displayed and a link to an
-individual store page is provided that shows additional
-information such as a picture and a description.
+.. _GeoDjango:
+.. _`installation instructions`:
-.. _`django-oscar`:
+Spatialite is another option although it can be tricky to set up. On Ubuntu,
+you can do the following::
+ $ sudo apt-get install spatialite-bin libspatialite3 libgeos++-dev libgdal-dev libproj0
+The ``pysqlite`` python package is also required although it doesn't support C
+extensions by default. To work-around this, there are two options:
+1. Download the package, edit ``setup.cfg`` to enable C extensions and install::
+ $ pip install pysqlite --no-install
+ $ vim $VIRTUALENV/build/pysqlite/setup.cfg
+ $ pip install pysqlite
+2. Use a custom branch::
+ $ pip install git+git://
+.. _`geodjango's installation guide`: .. _`pysqlite`:
-``django-oscar-stores`` uses geodjango_ which is part of the regular Django
-installation but has additional installation requirements for a GIS-enabled
-database. GIS extensions are available for all the database backends shipped
-with Django (with some limitations) for more details on setting them up please
-refer to the `geodjango's installation guide`_.
+First, ensure you are using a spatial database and have django-oscar installed.
-Setting up ``django-oscar-stores`` with Oscar_ is fairly simple. If you don't
-have an Oscar project up and running please refer to its documentation_ to set
-it up. With your Oscar project ready to go, you can install
-``django-oscar-stores`` simply by running::
+Install package::
pip install django-oscar-stores
-Now that you have the stores app installed, all you need to do
-add it to your ``INSTALLED_APPS`` settings::
+then add ``stores`` to ``INSTALLED_APPS``. Now update your root ````::
- ....
- 'stores',
- ....
- ]
-and update your ```` to be able to access the stores section
-in the dashboard and see the overview and detail pages for stores. A
-sample configuration (as used in the sandbox) might look similar to
from import shop
from import application as stores_app
@@ -74,76 +78,48 @@ this::
url(r'^stores/', include(stores_app.urls)),
-You also need to include the default settings::
- from stores.defaults import *
-And that's all you need to do. Running the server of your Oscar project, you
-should now have access to the `store manager`_ in the dashboard as well as a
-overview_ page displayed to your customers.
You also need to download the `GeoIP data files`_ and set ``GEOIP_PATH`` to point to the
appropriate directory.
.. _`GeoIP data files`:
-Setting up *spatialite* in Ubuntu
-I am using *spatialite* for local development and found the install
-instructions on geodjango_ a bit too much as most of the required
-libaries come packed for Ubuntu. In general, all you have to do
-to setup *spatialite* is run::
- $ sudo apt-get install spatialite-bin libspatialite3 libgeos++-dev libgdal-dev libproj0
-I am assuming that you want to setup the actual python package
-`pysqlite`_ in ``virtualenv`` instead of installing globally. This
-is it a bit tricky because *pysqlite* has extension support
-disabled by default (installing through pip). One way is to download
-the source, enable the extension support and install it manually.
-The nicer solution is to use a *pysqlite* clone that has the support
-enabled by default and can be installed from github using pip. You
-can do it by either installing::
- $ pip install git+git://
+* ``STORES_GEOGRAPHIC_SRID`` (default: ``3577``). This is used for distance
+ calculations. See for more details.
-Or by installing all the development-specific requirements for
-``django-oscar-stores`` in the ``requirements.txt`` file in the
-project root::
- $ pip install -r requirements.txt
-.. _Oscar:
-.. _documentation:
-.. _`store manager`: http://localhost:8000/dashboard/stores
-.. _overview: http://localhost:8000/stores
-.. _geodjango:
-.. _`geodjango's installation guide`:
-.. _`pysqlite`:
+* ``STORES_GEODETIC_SRID`` (default: ``4326``).
There is sandbox site within the repo which is a sample Oscar project that uses
the stores extension. Set this up with::
make sandbox
-Fetch the GeoIP files with::
+then fetch the GeoIP files with::
make geoip
-A fixture is loaded which provides a superuser to test the dashboard with::
+This loads a fixture which provides a superuser to test the dashboard with::
username: superuser
password: testing
+Run tests with::
+ ./
+Current CI status:
+.. image::
+ :target:!/elbaschid/django-oscar
``django-oscar-stores`` is released under the permissive `New BSD license`_.
@@ -1,153 +0,0 @@
-# Makefile for Sphinx documentation
-# You can set these variables from the command line.
-SPHINXBUILD = sphinx-build
-BUILDDIR = _build
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-# the i18n builder cannot share the environment and doctrees with the others
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
- @echo "Please use \`make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " dirhtml to make HTML files named index.html in directories"
- @echo " singlehtml to make a single large HTML file"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " devhelp to make HTML files and a Devhelp project"
- @echo " epub to make an epub"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " latexpdf to make LaTeX files and run them through pdflatex"
- @echo " text to make text files"
- @echo " man to make manual pages"
- @echo " texinfo to make Texinfo files"
- @echo " info to make Texinfo files and run them through makeinfo"
- @echo " gettext to make PO message catalogs"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
- -rm -rf $(BUILDDIR)/*
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
- $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
- @echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
- @echo
- @echo "Build finished; now you can process the pickle files."
- @echo
- @echo "Build finished; now you can process the JSON files."
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in $(BUILDDIR)/htmlhelp."
- @echo
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-oscar-stores.qhcp"
- @echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-oscar-stores.qhc"
- $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
- @echo
- @echo "Build finished."
- @echo "To view the help file:"
- @echo "# mkdir -p $$HOME/.local/share/devhelp/django-oscar-stores"
- @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-oscar-stores"
- @echo "# devhelp"
- @echo
- @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
- @echo
- @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
- @echo "Run \`make' in that directory to run these through (pdf)latex" \
- "(use \`make latexpdf' here to do that automatically)."
- @echo "Running LaTeX files through pdflatex..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
- @echo
- @echo "Build finished. The text files are in $(BUILDDIR)/text."
- @echo
- @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
- @echo
- @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
- @echo "Run \`make' in that directory to run these through makeinfo" \
- "(use \`make info' here to do that automatically)."
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
- @echo "Running Texinfo files through makeinfo..."
- make -C $(BUILDDIR)/texinfo info
- @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
- $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
- @echo
- @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
- @echo
- @echo "The overview file is in $(BUILDDIR)/changes."
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in $(BUILDDIR)/linkcheck/output.txt."
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
- @echo "Testing of doctests in the sources finished, look at the " \
- "results in $(BUILDDIR)/doctest/output.txt."
Oops, something went wrong.

0 comments on commit 6cb7dc7

Please sign in to comment.