Initial reorg of docs (#510)

* Initial cut for cleaning up docs

* Second run-through for updated docs

* Updated index file

* Fixed typo

Author: Ross Mechanic

CONTRIBUTING.rst

@@ -82,7 +82,7 @@ In order to add translations, refer to Django's `translation docs`_ and follow t
 steps:
 
 1. Ensure that Django is installed
-2. Invoke ``django-admin makemessages -l <LOCALE NAME> in the repository's root
+2. Invoke ``django-admin makemessages -l <LOCALE NAME>`` in the repository's root
    directory.
 3. Add translations to the created
    ``simple_history/locale/<LOCALE NAME>/LC_MESSAGES/django.po`` file.

README.rst

@@ -47,9 +47,13 @@ Getting Help
 
 Documentation is available at https://django-simple-history.readthedocs.io/
 
-Issue tracker is at https://github.com/treyhunner/django-simple-history/issues
-
-Pull requests are welcome.  Read the CONTRIBUTING file for tips on
+Pull requests are welcome.  Read the `CONTRIBUTING`_ file for tips on
 submitting a pull request.
 
-.. _PyPI: https://pypi.python.org/pypi/django-email-log/
+.. _CONTRIBUTING: https://github.com/treyhunner/django-simple-history/blob/master/CONTRIBUTING.rst
+
+License
+-------
+
+This project is licensed under the
+`BSD 3-Clause license <https://choosealicense.com/licenses/bsd-3-clause/>`_.

docs/admin.rst

@@ -0,0 +1,70 @@
+Admin Integration
+-----------------
+
+To allow viewing previous model versions on the Django admin site, inherit from
+the ``simple_history.admin.SimpleHistoryAdmin`` class when registering your
+model with the admin site.
+
+This will replace the history object page on the admin site and allow viewing
+and reverting to previous model versions.  Changes made in admin change forms
+will also accurately note the user who made the change.
+
+.. image:: screens/1_poll_history.png
+
+Clicking on an object presents the option to revert to that version of the object.
+
+.. image:: screens/2_revert.png
+
+(The object is reverted to the selected state)
+
+.. image:: screens/3_poll_reverted.png
+
+Reversions like this are added to the history.
+
+.. image:: screens/4_history_after_poll_reverted.png
+
+An example of admin integration for the ``Poll`` and ``Choice`` models:
+
+.. code-block:: python
+
+    from django.contrib import admin
+    from simple_history.admin import SimpleHistoryAdmin
+    from .models import Poll, Choice
+
+    admin.site.register(Poll, SimpleHistoryAdmin)
+    admin.site.register(Choice, SimpleHistoryAdmin)
+
+Changing a history-tracked model from the admin interface will automatically record the user who made the change (see :doc:`/user_tracking`).
+
+
+Displaying custom columns in the admin history list view
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the history log displays one line per change containing
+
+* a link to the detail of the object at that point in time
+* the date and time the object was changed
+* a comment corresponding to the change
+* the author of the change
+
+You can add other columns (for example the object's status to see
+how it evolved) by adding a ``history_list_display`` array of fields to the
+admin class
+
+.. code-block:: python
+
+    from django.contrib import admin
+    from simple_history.admin import SimpleHistoryAdmin
+    from .models import Poll, Choice
+
+
+    class PollHistoryAdmin(SimpleHistoryAdmin):
+        list_display = ["id", "name", "status"]
+        history_list_display = ["status"]
+        search_fields = ['name', 'user__username']
+
+    admin.site.register(Poll, PollHistoryAdmin)
+    admin.site.register(Choice, SimpleHistoryAdmin)
+
+
+.. image:: screens/5_history_list_display.png

docs/reference.rst renamed to docs/common_issues.rst

@@ -3,15 +3,15 @@ Common Issues
 
 Bulk Creating and Queryset Updating
 -----------------------------------
-Django Simple History functions by saving history using a ``post_save`` signal
+``django-simple-history`` functions by saving history using a ``post_save`` signal
 every time that an object with history is saved. However, for certain bulk
 operations, such as bulk_create_ and `queryset updates <https://docs.djangoproject.com/en/2.0/ref/models/querysets/#update>`_,
 signals are not sent, and the history is not saved automatically. However,
-Django Simple History provides utility functions to work around this.
+``django-simple-history`` provides utility functions to work around this.
 
 Bulk Creating a Model with History
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-As of Django Simple History 2.2.0, we can use the utility function
+As of ``django-simple-history`` 2.2.0, we can use the utility function
 ``bulk_create_with_history`` in order to bulk create objects while saving their
 history:
 
@@ -63,7 +63,6 @@ As the Django documentation says::
 .. _queryset updates: https://docs.djangoproject.com/en/2.0/ref/models/querysets/#update
 
 
-
 Tracking Custom Users
 ---------------------