Add RelativesAdmin to docs and improve docs some

docs/conf.py

@@ -16,12 +16,17 @@
 import sys
 
 import django
+from django.conf import settings
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(".."))
 
+settings.configure(
+    DEBUG=True,
+    INSTALLED_APPS=["django.contrib.contenttypes"],
+)
 django.setup()
 
 project_directory = os.path.join(os.path.basename(__file__), "..")

docs/index.rst

@@ -1,8 +1,17 @@
 django-relatives
 ================
 
-django-relatives provides various utilites that make it easy to link related
-objects in the Django admin site.
+django-relatives provides various utilites that make it easy to link related objects in the Django admin site.
+
+Uses
+----
+
+The main usages of this Django app are:
+
+- :ref:`Linking to foreign keys in change lists <change_lists>`
+- :ref:`Linking to foreign keys in change forms <change_forms>`
+- :ref:`Linking to reverse relations on change forms <reverse_relations>`
+- :ref:`Linking to foreign keys in inlines <links_in_inlines>`
 
 Contents
 --------
@@ -16,27 +25,12 @@ Contents
 Contributing
 ------------
 
-Visit the project `on Github`_ to view the source, submit issues and pull
-requests.
+Visit the project `on Github`_ to view the source, submit issues and pull requests.
 
 .. _on github: https://github.com/treyhunner/django-relatives
 
-Examples
---------
-
-Turn read-only foreign key fields into hyperlinks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/object_edit_link_example.png
-
-Link to child objects in the sidebar
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/related_objects_example.png
-
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`
-

docs/usage.rst

@@ -13,110 +13,47 @@ Install from `PyPI`_:
 .. _PyPI: https://pypi.python.org/pypi/django-relatives/
 
 
-Since relatives uses cache, you can set settings to change the defaults:
-
-.. code-block:: python
-
-    RELATIVES_CACHE_KEY = 'relatives_cache'
-    RELATIVES_CACHE_TIME = int(60*60*24)
+.. _change_lists:
 
+Linking to foreign keys in change lists
+---------------------------------------
 
-Edit links in inlines
----------------------
-
-To link to an inline object, include the
-:func:`object_link <relatives.utils.object_link>` utility function in your
-admin inline's ``fields`` list and ``readonly_fields`` list.
-
-Example
-~~~~~~~
-
-Code
-++++
+The easiest way to automatically to turn foreign key columns into hyperlinks in a Django admin change list is to inherit from :func:`RelativesAdmin <relatives.RelativesAdmin>` in your model admin.
 
 .. code-block:: python
 
     from django.contrib import admin
-    from relatives.utils import object_link
+    from relatives import RelativesAdmin
 
-    from models import Company, Employee
-
-
-    class EmployeeInline(admin.TabularInline):
-        model = Employee
-        fields = [object_link, 'first_name', 'last_name']
-        readonly_fields = fields
-        extra = 0
-        max_num = 0
-        can_delete = False
+    from .models import Company, Employee
 
 
+    @admin.register(Company)
     class CompanyAdmin(admin.ModelAdmin):
-        inlines = [EmployeeInline]
+        list_display = ["name"]
 
-    admin.site.register(Company, CompanyAdmin)
 
+    @admin.register(Employee)
+    class EmployeeAdmin(RelativesAdmin):
+        list_display = ["first_name", "last_name", "company"]
 
-    admin.site.register(Employee)
 
 Screenshot
 ++++++++++
 
-.. figure:: images/object_link_example.png
-
-
-Customizing inline edit links
------------------------------
-
-To customize the link text for your inline links, use
-the :func:`object_edit_link <relatives.utils.object_edit_link>` utility
-function instead, specifying the edit text
-and blank text (both are optional).
-
-Example
-~~~~~~~
-
-Code
-++++
-
-.. code-block:: python
-
-    from django.contrib import admin
-    from relatives.utils import object_edit_link
-
-    from models import Company, Employee
-
-
-    class EmployeeInline(admin.TabularInline):
-        model = Employee
-        edit_link = object_edit_link("Edit")
-        fields = [edit_link, 'employee_id', 'first_name', 'last_name']
-        readonly_fields = [edit_link]
-
-
-    class CompanyAdmin(admin.ModelAdmin):
-        inlines = [EmployeeInline]
-
-    admin.site.register(Company, CompanyAdmin)
-
+When viewing the change list for the employee model, you'll now see that the company column contents are all linked to the appropriate change form page for each company.
 
-    admin.site.register(Employee)
-
-Screenshot
-++++++++++
+.. figure:: images/relatives_admin_example.png
 
-.. figure:: images/object_edit_link_example.png
 
+.. _change_forms:
 
-Linking to foreign keys
------------------------
+Linking to foreign keys in change forms
+---------------------------------------
 
-The :func:`contents_or_fk_link <relatives.templatetags.relatives.contents_or_fk_link>` template filter can be used to link to foreign keys
-for readonly admin form fields.
+The :func:`contents_or_fk_link <relatives.templatetags.relatives.contents_or_fk_link>` template filter can be used to link to foreign keys for readonly admin form fields.
 
-Django Relatives also provides a replacement for the
-``admin/includes/fieldset.html`` template which can be used to automatically
-link to all readonly foreign key fields in change forms.
+Django Relatives also provides a replacement for the ``admin/includes/fieldset.html`` template which can be used to automatically link to all readonly foreign key fields in change forms.
 
 To use the custom fieldset template you must add ``relatives`` to
 ``INSTALLED_APPS`` in your settings file:
@@ -141,8 +78,10 @@ Example Screenshot
 .. figure:: images/contents_or_fk_link_example.png
 
 
-Linking to reverse relations
-----------------------------
+.. _reverse_relations:
+
+Linking to reverse relations on change forms
+--------------------------------------------
 
 The :func:`related_objects <relatives.templatetags.relatives.related_objects>` template tag makes it easy to link to change lists
 filtered for reverse relations (objects that have a foreign key to a given
@@ -177,7 +116,7 @@ Code
 
     from django.contrib import admin
 
-    from models import Company, Employee
+    from .models import Company, Employee
 
 
     class CompanyAdmin(admin.ModelAdmin):
@@ -208,3 +147,98 @@ extends from ``relatives/change_form.html``::
 
 Also make sure this template file is in a custom template directory or an app
 listed before your admin app in ``INSTALLED_APPS``.
+
+
+.. _links_in_inlines:
+
+Edit links in inlines
+---------------------
+
+To link to an inline object, include the :func:`object_link <relatives.utils.object_link>` utility function in your admin inline's ``fields`` list and ``readonly_fields`` list.
+
+Example
+~~~~~~~
+
+Code
+++++
+
+.. code-block:: python
+
+    from django.contrib import admin
+    from relatives.utils import object_link
+
+    from .models import Company, Employee
+
+
+    class EmployeeInline(admin.TabularInline):
+        model = Employee
+        fields = [object_link, 'first_name', 'last_name']
+        readonly_fields = fields
+        extra = 0
+        max_num = 0
+        can_delete = False
+
+
+    class CompanyAdmin(admin.ModelAdmin):
+        inlines = [EmployeeInline]
+
+    admin.site.register(Company, CompanyAdmin)
+
+
+    admin.site.register(Employee)
+
+Screenshot
+++++++++++
+
+.. figure:: images/object_link_example.png
+
+
+Customizing inline edit links
+-----------------------------
+
+To customize the link text for your inline links, use the :func:`object_edit_link <relatives.utils.object_edit_link>` utility function instead, specifying the edit text and blank text (both are optional).
+
+Example
+~~~~~~~
+
+Code
+++++
+
+.. code-block:: python
+
+    from django.contrib import admin
+    from relatives.utils import object_edit_link
+
+    from .models import Company, Employee
+
+
+    class EmployeeInline(admin.TabularInline):
+        model = Employee
+        edit_link = object_edit_link("Edit")
+        fields = [edit_link, 'employee_id', 'first_name', 'last_name']
+        readonly_fields = [edit_link]
+
+
+    class CompanyAdmin(admin.ModelAdmin):
+        inlines = [EmployeeInline]
+
+    admin.site.register(Company, CompanyAdmin)
+
+
+    admin.site.register(Employee)
+
+Screenshot
+++++++++++
+
+.. figure:: images/object_edit_link_example.png
+
+
+Customizing settings
+--------------------
+
+Since relatives uses cache, you can update the settings module to change the defaults if you'd like:
+
+.. code-block:: python
+
+    RELATIVES_CACHE_KEY = 'relatives_cache'
+    RELATIVES_CACHE_TIME = int(60*60*24)