[Docs] Explains how to use django-reversion with polymorphic models.

docs/admin.rst

@@ -46,13 +46,18 @@ use the ``base_form`` and ``base_fieldsets`` instead. The ``PolymorphicChildMode
 automatically detect the additional fields that the child model has, display those in a separate fieldset.
 
 
+.. _admin-example:
+
 Example
 -------
 
+The models are taken from :ref:`advanced-features`.
+
 .. code-block:: python
 
     from django.contrib import admin
     from polymorphic.admin import PolymorphicParentModelAdmin, PolymorphicChildModelAdmin
+    from .models import ModelA, ModelB, ModelC
 
 
     class ModelAChildAdmin(PolymorphicChildModelAdmin):

docs/advanced.rst

@@ -1,8 +1,11 @@
+.. _advanced-features:
+
 Advanced features
 =================
 
 In the examples below, these models are being used::
 
+    from django.db import models
     from polymorphic import PolymorphicModel
 
     class ModelA(PolymorphicModel):

docs/index.rst

@@ -30,8 +30,8 @@ Features
 * Full admin integration.
 * ORM integration:
 
- * support for ForeignKey, ManyToManyField, OneToOneField descriptors.
- * support for proxy models
+ * Support for ForeignKey, ManyToManyField, OneToOneField descriptors.
+ * Support for proxy models.
  * Filtering/ordering of inherited models (``ArtProject___artist``).
  * Filtering model types: ``instance_of(...)`` and ``not_instance_of(...)``
  * Combining querysets of different models (``qs3 = qs1 | qs2``)
@@ -59,6 +59,7 @@ Advanced topics
 
    advanced
    managers
+   third-party
    changelog
    contributing
 

docs/third-party.rst

@@ -0,0 +1,56 @@
+Third-party applications support
+================================
+
+Django-reversion support
+------------------------
+
+`Django-reversion <https://github.com/etianen/django-reversion>`_ works as
+expected with polymorphic models.  However, they require more setup than
+standard models.  We have to face these problems:
+
+* The children models are not registered in the admin site.
+  You will therefore need to manually register them to django-reversion.
+* Polymorphic models use
+  `multi-table inheritance <https://docs.djangoproject.com/en/dev/topics/db/models/#multi-table-inheritance>`_.
+  The django-reversion wiki explains
+  `how to deal with this <https://github.com/etianen/django-reversion/wiki/Low-level-API#multi-table-inheritance>`_.
+
+
+Example
+.......
+
+The admin :ref:`admin-example` becomes:
+
+.. code-block:: python
+
+    from django.contrib import admin
+    from polymorphic.admin import PolymorphicParentModelAdmin, PolymorphicChildModelAdmin
+    import reversion
+    from reversion import VersionAdmin
+    from .models import ModelA, ModelB, ModelC
+
+
+    class ModelAChildAdmin(PolymorphicChildModelAdmin):
+        base_model = ModelA
+        base_form = ...
+        base_fieldsets = (
+            ...
+        )
+
+    class ModelBAdmin(VersionAdmin, ModelAChildAdmin):
+        # define custom features here
+
+    class ModelCAdmin(ModelBAdmin):
+        # define custom features here
+
+
+    class ModelAParentAdmin(VersionAdmin, PolymorphicParentModelAdmin):
+        base_model = ModelA
+        child_models = (
+            (ModelB, ModelBAdmin),
+            (ModelC, ModelCAdmin),
+        )
+
+    reversion.register(ModelB, follow=['modela_ptr'])
+    reversion.register(ModelC, follow=['modelb_ptr'])
+    admin.site.register(ModelA, ModelAParentAdmin)