Updated documentation formatting and information for 1.4 release.

README.md

@@ -1,22 +1,39 @@
-admin-sortable
+# Django Admin Sortable
-=============
 
-What is it?
+This project makes it easy to add drag-and-drop ordering to any model in
-=============
+Django admin. Inlines for a sortable model may also be made sortable,
-The adminsortable app adds generic drag-and-drop facilities
+enabling individual items or groups of items to be sortable.
-to any Django model class or Inlines via Django Admin and jQueryUI.
 
-Installation
+## Requirements
-=============
+jQuery
-1. Run ``setup.py`` or add ``adminsortable`` to your PYTHONPATH.
+
-2. Copy the ``adminsortable`` folder from the static folder to the
+
-location you server static files from, or if you're using the StaticFiles app
+## Installation
- https://docs.djangoproject.com/en/1.3/ref/contrib/staticfiles/,
+1. pip install django-admin-sortable
-run: $ python manage.py collectstatic to move the files to the location
+
-you've specified for static files.
+--or--
-3. Add ``adminsortable`` to your INSTALLED_APPS.
+
-4. Ensure "django.core.context_processors.static" is in your TEMPLATE_CONTEXT_PROCESSORS.
+Download django-admin-sortable from [source](https://github.com/iambrandontaylor/django-admin-sortable/archive/master.zip)
-5. Have a look at the included sample_project to see working examples.
+
+1. Unzip the directory and cd into the uncompressed project directory
+2. *Optional: Enable your virtualenv
+3. Run `$ python setup.py install` or add `adminsortable` to your PYTHONPATH.
+
+
+## Configuration
+1. Add `adminsortable` to your `INSTALLED_APPS`.
+2. Ensure `django.core.context_processors.static` is in your `TEMPLATE_CONTEXT_PROCESSORS`.
+
+### Static Media
+Preferred:
+Use the [staticfiles app](https://docs.djangoproject.com/en/1.4/ref/contrib/staticfiles/)
+
+Alternate:
+Copy the `adminsortable` folder from the `static` folder to the
+location you server static files from.
+
+### Testing
+Have a look at the included sample_project to see working examples.
 The login credentials for admin are: admin/admin
 
 When a model is sortable, a tool-area link will be added that says "Change Order".
@@ -25,19 +42,19 @@ the records into order.
 
 Tabular inlines may be drag-and-dropped into any order directly from the change form.
 
-Usage
+
-=============
+## Usage
-Models
+
-----------------------
+### Models
-To add sorting to a model, your model needs to inherit from ``Sortable`` and
+To add sorting to a model, your model needs to inherit from `Sortable` and
-have an inner Meta class that inherits from ``Sortable.Meta``
+have an inner Meta class that inherits from `Sortable.Meta`
 
     #models.py
     from adminsortable.models import Sortable
 
     class MySortableClass(Sortable):
         class Meta(Sortable.Meta):
-			pass
+            pass
 
         title = models.CharField(max_length=50)
 
@@ -57,7 +74,7 @@ even if that model does not inherit from Sortable:
 
     class Project(Sortable):
         class Meta(Sortable.Meta):
-			pass
+            pass
 
         category = SortableForeignKey(Category)
         title = models.CharField(max_length=50)
@@ -68,14 +85,12 @@ even if that model does not inherit from Sortable:
 
 Sortable has one field: `order` and adds a default ordering value set to `order`.
 
-South
+### South
-------
+If you're adding Sorting to an existing model, it is recommended that you use [django-south](http://south.areacode.com/) to create a migration to add the "order" field to your model.
-If you're adding Sorting to an existing model, it is recommended that you use django-south,
-http://south.areacode.com/ to create a migration to add the "order" field to your model.
 
 
-*Django Admin Usage*
+### Django Admin
-To enable sorting in the admin, you need to inherit from SortableAdmin:
+To enable sorting in the admin, you need to inherit from `SortableAdmin`:
 
     from django.contrib import admin
     from myapp.models import MySortableClass
@@ -104,7 +119,7 @@ SortableStackedInline:
     class MySortableStackedInline(SortableStackedInline):
        """Your inline options go here"""
 
-!!! *IMPORTANT* !!!
+*** IMPORTANT  ***
 With stacked inline models, their height can dynamically increase,
 which can cause sortable stacked inlines to not behave as expected.
 If the height of the stacked inline is going to be very tall, I would
@@ -112,8 +127,7 @@ suggest NOT using SortableStackedInline. I'm currently working on
 a way to make this more usable.
 
 
-Potential Gotcha
+### Potential Gotcha
-=============
 
 If you have an existing model that you're now making Sortable, existing
 rows won't have an "order" attribute. Django-admin-sortable depends on
@@ -123,16 +137,15 @@ A good rule of thumb if you're adding django-admin-sortable to an existing
 project is to create a Data Migration using South to set the "order" column
 according to your needs.
 
-For example, if you have a SortableForeignKey field, you would need to set
+For example, if you have a `SortableForeignKey` field, you would need to set
 the "order" column relative to that field, instead of setting the "order"
 column in linear succession.
 
-See: http://south.readthedocs.org/en/latest/tutorial/part3.html for more
+See: [this link](http://south.readthedocs.org/en/latest/tutorial/part3.html) for more
 information on Data Migrations.
 
 
-Rationale
+### Rationale
-=============
 Other projects have added drag-and-drop ordering to the ChangeList
 view, however this introduces a couple of problems...
 
@@ -145,41 +158,20 @@ impossible.
 - The ChangeList supports in-line editing, and adding drag-and-drop
 ordering on top of that just seemed a little much in my opinion.
 
-Status
+### Status
-=============
+django-admin-sortable is currently used in production.
-admin-sortable is currently used in production.
 
 
-What's new in 1.3.8?
+### What's new in 1.4?
-=============
+- Django 1.5 compatibility
-- CSS fixes for tabular inlines courtesty of @ionelmc: https://github.com/ionelmc
-- Updated documentation
 
-Features
-=============
-Current
----------
-- Supports Django 1.4+
-- Adds an admin view to any model that inherits from Sortable and SortableAdmin
-that allows you to drag and drop objects into any order via jQueryUI.
-- Adds drag and drop ordering to Tabular and Stacked Inline models that inherit from
-SortableTabularInline and SortableStackedInline
-- Allows ordering of objects that are sorted on a Foreign Key, and adds ordering
-to the foreign key object if it also inherits from Sortable.
-- Supports non-integer primary keys.
 
-Future
+### Future
-------
 - Support for foreign keys that are self referential
 - More unit tests
+- Move unit tests out of sample project
+- Travis CI integration
 
-Requirements
-=============
-Sample Project
-----------------
-Requires django-appmedia, included
 
-License
+### License
-=============
+django-admin-sortable is released under the Apache Public License v2.
-The admin-sortable app is released
-under the Apache Public License v2.