Set default settings for admin listing and filtering, re #156

Make it easy to add workflow features to the admin by referring to
`WorkflowMixinAdmin.list_display` and `WorkflowMixinAdmin.list_filter`
in admin classes.

Also documented list filters, and the requirement that target models
extend `WorkflowStepMixin` or provide an equivalent generic
relationship field.

docs/topics/workflow.md

@@ -22,6 +22,19 @@ The `icekit.workflow.models.WorkflowStep` model allows you to assign workflow
 information to any model in the system via a generic foreign key (GFK)
 relationship, and to store related workflow status information.
 
+### Reverse model relationships
+
+To make the relationships between workflow steps and a target object navigable
+in reverse, the target object class should either:
+
+ * extend from the helper abstract mixin model class
+   `icekit.workflow.models.WorkflowStepMixin`, or
+ * add an equivalent `GenericRelation` relationships attribute to the model.
+
+Once the reverse relationship is made navigable in this way you can look up the
+workflow steps associated with an item more easily using the `workflow_steps`
+relationship attribute.
+
 
 ## Workflow Admin
 
@@ -32,16 +45,26 @@ information and features for use in your Django admin classes.
 
 Admin list views columns you can add to `list_display`:
 
-* `workflow_steps_column` renders text descriptions of the workflow steps assigned
-  to an item
-* `created_by_column` renders the user who first created an item in the Django admin
-* `last_edited_by_column` renders the user to last edited (added or changed) an
-  item in the admin.
+ * `workflow_steps_column` renders text descriptions of the workflow steps assigned
+   to an item
+ * `created_by_column` renders the user who first created an item in the Django admin
+ * `last_edited_by_column` renders the user to last edited (added or changed) an
+   item in the admin.
 
 NOTE: The model change tracking is based on Django admin's `LogEntry`
 mechanisms and is fairly simplistic: it will not track model changes performed
 outside the admin.
 
+Admin filter attributes you can add to `list_filter`:
+
+ * `workflow_steps__status` to show only items related to a workflow step with
+   the given status, such as "Approved"
+ * `workflow_steps__assigned_to` to show only items assigned to a user.
+
+NOTE: For these admin filters to work the relevant model must implement a
+`GenericRelation` field named `workflow_steps`, which is easiest to do by
+extending from `WorkflowStepMixin` as described above.
+
 ### WorkflowStepTabularInline
 
 The `icekit.workflow.admin.WorkflowStepTabularInline` provides an inline for

icekit/workflow/admin.py

@@ -32,6 +32,10 @@ class WorkflowStepTabularInline(GenericTabularInline):
 
 
 class WorkflowMixinAdmin(admin.ModelAdmin):
+    list_display = (
+        "created_by_column", "last_edited_by_column", "workflow_steps_column")
+    list_filter = (
+        "workflow_steps__status", "workflow_steps__assigned_to")
 
     def _get_obj_ct(self, obj):
         """ Look up and return object's content type and cache for reuse """