Permalink
Browse files

Improve README

* Add screenshots
* Better installation instructions
  • Loading branch information...
1 parent 6eda984 commit 6cb7dc76ef8c09312822f438d9a6d991fec61c70 @codeinthehole codeinthehole committed Jan 25, 2013
View
@@ -1,63 +1,67 @@
-================================================
-Store Extension for the Oscar Ecommerce Platform
-================================================
+============
+Oscar stores
+============
-.. image:: https://secure.travis-ci.org/elbaschid/django-oscar-stores.png
- :target: http://travis-ci.org/#!/elbaschid/django-oscar
+This is an extension for django-oscar_ that adds support for stores. It
+provides:
-Warning
--------
-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: https://github.com/tangentlabs/django-oscar
-Introduction
-============
+* 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
+
+Screenshots
+-----------
+
+.. image:: https://github.com/tangentlabs/django-oscar-stores/raw/master/docs/images/locator.thumb.png
+ :target: https://github.com/tangentlabs/django-oscar-stores/raw/master/docs/images/locator.png
+
+.. image:: https://github.com/tangentlabs/django-oscar-stores/raw/master/docs/images/detail.thumb.png
+ :target: https://github.com/tangentlabs/django-oscar-stores/raw/master/docs/images/detail.png
+
+Dependencies
+------------
-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: https://docs.djangoproject.com/en/1.4/ref/contrib/gis
+.. _`installation instructions`: https://docs.djangoproject.com/en/1.4/ref/contrib/gis/install
-.. _`django-oscar`: http://github.com/tangentlabs/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://github.com/tinio/pysqlite.git@extension-enabled#egg=pysqlite
+
+.. _`geodjango's installation guide`: .. _`pysqlite`: http://code.google.com/p/pysqlite
Installation
-============
+------------
-``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 ``urls.py``::
- INSTALLED_APPS = [
- ....
- 'stores',
- ....
- ]
-
-and update your ``urls.py`` 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
-this::
from oscar.app import shop
from stores.app 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`: https://docs.djangoproject.com/en/dev/ref/contrib/gis/geoip/
+Settings
+--------
-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://github.com/tinio/pysqlite.git@extension-enabled#egg=pysqlite
+* ``STORES_GEOGRAPHIC_SRID`` (default: ``3577``). This is used for distance
+ calculations. See http://spatialreference.org 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: http://oscarcommerce.com
-.. _documentation: http://django-oscar.readthedocs.org/en/latest
-.. _`store manager`: http://localhost:8000/dashboard/stores
-.. _overview: http://localhost:8000/stores
-.. _geodjango: https://docs.djangoproject.com/en/1.4/ref/contrib/gis
-.. _`geodjango's installation guide`: https://docs.djangoproject.com/en/1.4/ref/contrib/gis/install
-.. _`pysqlite`: http://code.google.com/p/pysqlite
+* ``STORES_GEODETIC_SRID`` (default: ``4326``).
Contributing
-============
+------------
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::
email: superuser@example.com
username: superuser
password: testing
+Run tests with::
+
+ ./runtests.py
+
+Current CI status:
+
+.. image:: https://secure.travis-ci.org/elbaschid/django-oscar-stores.png
+ :target: http://travis-ci.org/#!/elbaschid/django-oscar
License
-=======
+-------
``django-oscar-stores`` is released under the permissive `New BSD license`_.
View
@@ -1,153 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-BUILDDIR = _build
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
-help:
- @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)"
-
-clean:
- -rm -rf $(BUILDDIR)/*
-
-html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
- $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
- @echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
- @echo
- @echo "Build finished; now you can process the pickle files."
-
-json:
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
- @echo
- @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
- $(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."
-
-qthelp:
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
- @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"
-
-devhelp:
- $(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"
-
-epub:
- $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
- @echo
- @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @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)."
-
-latexpdf:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @echo "Running LaTeX files through pdflatex..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
- $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
- @echo
- @echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
- $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
- @echo
- @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
- $(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)."
-
-info:
- $(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."
-
-gettext:
- $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
- @echo
- @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
- @echo
- @echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
- $(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."
-
-doctest:
- $(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.