Start docs updates

docs/usage.rst → docs/change.rst

@@ -1,24 +1,94 @@
-Usage
-=====
+Links on Change Pages
+=====================
 
-Installation
-------------
 
-Install from `PyPI`_:
+Linking all foreign keys
+-----------------------
+
+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.
+
+To use the custom fieldset template you must add ``relatives`` to
+``INSTALLED_APPS`` in your settings file:
+
+.. code-block:: python
+
+    INSTALLED_APPS = (
+        ...
+        'relatives',
+    )
+
+Next create a ``admin/includes/fieldset.html`` template file::
+
+    {% extends "relatives/includes/fieldset.html" %}
+
+Also make sure this template file is in a custom template directory or an app
+listed before your admin app in ``INSTALLED_APPS``.
+
+Example
+~~~~~~~
 
-.. code-block:: bash
+.. figure:: images/contents_or_fk_link_example.png
 
-    $ pip install django-relatives
 
-.. _PyPI: https://pypi.python.org/pypi/django-relatives/
+Linking to reverse relations
+----------------------------
 
+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
+object).
 
-Since relatives uses cache, you can set settings to change the defaults:
+Django Relatives also provides a custom ``change_form.html`` template that may
+be used to add a "Relations" sidebar to change forms.  This sidebar provides
+links to change list queries for all objects that contain a foreign key to the
+current object.
+
+To use the custom fieldset template you must add ``relatives`` to
+``INSTALLED_APPS`` in your settings file:
 
 .. code-block:: python
 
-    RELATIVES_CACHE_KEY = 'relatives_cache'
-    RELATIVES_CACHE_TIME = int(60*60*24)
+    INSTALLED_APPS = (
+        ...
+        'relatives',
+    )
+
+Now you can customize the change form template for your desired models/apps.
+The easiest way to link to reverse relations is to override the
+``change_form_template`` in your ``ModelAdmin`` subclass.
+
+Example
+~~~~~~~
+
+.. figure:: images/related_objects_example.png
+
+.. code-block:: python
+
+    from django.contrib import admin
+
+    from models import Company, Employee
+
+
+    class CompanyAdmin(admin.ModelAdmin):
+        change_form_template = 'relatives/change_form.html'
+
+    admin.site.register(Company, CompanyAdmin)
+
+
+    admin.site.register(Employee)
+
+
+Linking to reverse relations with custom template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you don't have access to change the ``ModelAdmin`` for your model or you are already customizing your model's admin change form, you will need to use a custom admin template instead.
+
+Create a ``admin/YOURAPP/YOURMODEL/change_form.html`` template file that extends from ``relatives/change_form.html``::
+
+    {% extends "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``.
 
 
 Edit links in inlines
@@ -31,8 +101,7 @@ admin inline's ``fields`` list and ``readonly_fields`` list.
 Example
 ~~~~~~~
 
-Code
-++++
+.. figure:: images/object_link_example.png
 
 .. code-block:: python
 
@@ -59,11 +128,6 @@ Code
 
     admin.site.register(Employee)
 
-Screenshot
-++++++++++
-
-.. figure:: images/object_link_example.png
-
 
 Customizing inline edit links
 -----------------------------
@@ -76,8 +140,7 @@ and blank text (both are optional).
 Example
 ~~~~~~~
 
-Code
-++++
+.. figure:: images/object_edit_link_example.png
 
 .. code-block:: python
 
@@ -101,110 +164,3 @@ Code
 
 
     admin.site.register(Employee)
-
-Screenshot
-++++++++++
-
-.. figure:: images/object_edit_link_example.png
-
-
-Linking to foreign keys
------------------------
-
-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.
-
-To use the custom fieldset template you must add ``relatives`` to
-``INSTALLED_APPS`` in your settings file:
-
-.. code-block:: python
-
-    INSTALLED_APPS = (
-        ...
-        'relatives',
-    )
-
-Next create a ``admin/includes/fieldset.html`` template file::
-
-    {% extends "relatives/includes/fieldset.html" %}
-
-Also make sure this template file is in a custom template directory or an app
-listed before your admin app in ``INSTALLED_APPS``.
-
-Example Screenshot
-~~~~~~~~~~~~~~~~~~
-
-.. figure:: images/contents_or_fk_link_example.png
-
-
-Linking to reverse relations
-----------------------------
-
-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
-object).
-
-Django Relatives also provides a custom ``change_form.html`` template that may
-be used to add a "Relations" sidebar to change forms.  This sidebar provides
-links to change list queries for all objects that contain a foreign key to the
-current object.
-
-To use the custom fieldset template you must add ``relatives`` to
-``INSTALLED_APPS`` in your settings file:
-
-.. code-block:: python
-
-    INSTALLED_APPS = (
-        ...
-        'relatives',
-    )
-
-Now you can customize the change form template for your desired models/apps.
-The easiest way to link to reverse relations is to override the
-``change_form_template`` in your ``ModelAdmin`` subclass.
-
-Example
-~~~~~~~
-
-Code
-++++
-
-.. code-block:: python
-
-    from django.contrib import admin
-
-    from models import Company, Employee
-
-
-    class CompanyAdmin(admin.ModelAdmin):
-        change_form_template = 'relatives/change_form.html'
-
-    admin.site.register(Company, CompanyAdmin)
-
-
-    admin.site.register(Employee)
-
-Screenshot
-++++++++++
-
-.. figure:: images/related_objects_example.png
-
-
-Linking to reverse relations with custom template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you don't have access to change the ``ModelAdmin`` for your model or you are
-already customizing your model's admin change form, you will need to use a
-custom admin template instead.
-
-Create a ``admin/YOURAPP/YOURMODEL/change_form.html`` template file that
-extends from ``relatives/change_form.html``::
-
-    {% extends "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``.

docs/changelist.rst

@@ -0,0 +1,18 @@
+Links in Change Lists
+=====================
+
+
+Linking related fields
+----------------------
+
+To automatically link foreign key and one-to-one fields to the relevant admin change page, inherit from ``RelativesAdmin``.
+
+TODO show code example and screenshot
+
+
+Linking ModelAdmin methods
+--------------------------
+
+To turn a ``ModelAdmin`` method to a specific foreign key or one-to-one field, use the ``link_related`` decorator.
+
+TODO show code example and screenshot

docs/index.rst

@@ -10,7 +10,9 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   usage
+   installation
+   changelist
+   change
    api
 
 Contributing

docs/installation.rst

@@ -0,0 +1,21 @@
+Usage
+=====
+
+Installation
+------------
+
+Install from `PyPI`_:
+
+.. code-block:: bash
+
+    $ pip install django-relatives
+
+.. _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 = 60*60*24