Merge pull request #144 from treyhunner/documentation

Update Documentation

Author: treyhunner

doc-requirements.txt

@@ -0,0 +1,2 @@
+Sphinx==1.2.3
+sphinx-autobuild==0.3.0

docs/advanced.rst

@@ -1,14 +1,16 @@
 Advanced Usage
 ==============
 
-Version-controlling with South
-------------------------------
+Database Migrations
+-------------------
 
-By default, Historical models live in the same app as the model they track.
-Historical models are tracked by South in the same way as any other model.
-Whenever the original model changes, the historical model will change also.
+By default, Historical models live in the same app as the model they
+track. Historical models are tracked by migrations in the same way as
+any other model. Whenever the original model changes, the historical
+model will change also.
 
-Therefore tracking historical models with South should work automatically.
+Therefore tracking historical models with migrations should work
+automatically.
 
 
 Locating past model instance
@@ -44,8 +46,10 @@ model history.
     <Poll: Poll object as of 2010-10-25 18:04:13.814128>
 
 
-History for Third-Party Model
------------------------------
+.. _register:
+
+History for a Third-Party Model
+-------------------------------
 
 To track history for a model you didn't create, use the
 ``simple_history.register`` utility.  You can use this to track models from
@@ -61,7 +65,7 @@ third-party apps you don't have control over.  Here's an example of using
     register(User)
 
 
-.. _recording_user:
+.. recording_user:
 
 Recording Which User Changed a Model
 ------------------------------------

docs/index.rst

@@ -10,6 +10,7 @@ Documentation
    :maxdepth: 2
 
    usage
+   reference
    advanced
 
 Code

docs/reference.rst

@@ -0,0 +1,25 @@
+Common Issues
+=============
+
+-   ``fields.E300``::
+
+        ERRORS:
+        custom_user.HistoricalCustomUser.history_user: (fields.E300) Field defines a relation with model 'custom_user.CustomUser', which is either not installed, or is abstract.
+
+    Use ``register()`` to track changes to the custom user model
+    instead of setting ``HistoricalRecords`` on the model directly.
+    See :ref:`register`.
+
+    The reason for this, is that unfortunately ``HistoricalRecords``
+    cannot be set directly on a swapped user model because of the user
+    foreign key to track the user making changes.
+
+-   ``HistoricalRecords`` is not inherited
+
+    Allowing ``HistoricalRecords`` to be inherited from abstract
+    models or other parents is a feature we would love to add. The
+    current contributors do not have a need for that feature at this
+    point, and need some help understanding how this feature should be
+    completed. Current work is in `#112`__.
+
+    __ https://github.com/treyhunner/django-simple-history/pull/112

docs/usage.rst

@@ -1,5 +1,5 @@
-Usage
-=====
+Quick Start
+===========
 
 Install
 -------
@@ -16,10 +16,37 @@ Install from PyPI with ``pip``:
 .. _crate.io: https://crate.io/packages/django-simple-history/
 
 
-Quickstart
-----------
+Configure
+---------
 
-Add ``simple_history`` to your ``INSTALLED_APPS``.
+Settings
+~~~~~~~~
+
+Add ``simple_history`` to your ``INSTALLED_APPS``
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # ...
+        'simple_history',
+    ]
+
+The historical models can track who made each change. To populate the
+history user automatically you can add middleware to your Django
+settings:
+
+.. code-block:: python
+
+    MIDDLEWARE_CLASSES = [
+        # ...
+        'simple_history.middleware.HistoryRequestMiddleware',
+    ]
+
+If you do not want to use the middleware, you can explicitly indicate
+the user making the change as documented in :ref:`recording_user`.
+
+Models
+~~~~~~
 
 To track history for a model, create an instance of
 ``simple_history.models.HistoricalRecords`` on the model.
@@ -46,20 +73,8 @@ Django tutorial:
 Now all changes to ``Poll`` and ``Choice`` model instances will be tracked in
 the database.
 
-The historical models can also track who made each change. To populate
-the history user automatically you can add middleware to your Django
-settings:
-
-.. code-block:: python
-
-    MIDDLEWARE_CLASSES = [
-        # ...
-        'simple_history.middleware.HistoryRequestMiddleware',
-    ]
-
-If you do not want to use the middleware, you can explicitly indicate
-the user making the change as indicated in the advanced usage
-documentation.
+Existing Projects
+~~~~~~~~~~~~~~~~~
 
 For existing projects, you can call the populate command to generate an
 initial change for preexisting model instances:
@@ -153,4 +168,3 @@ records for all ``Choice`` instances can be queried by using the manager on the
     <simple_history.manager.HistoryManager object at 0x1cc4290>
     >>> Choice.history.all()
     [<HistoricalChoice: Choice object as of 2010-10-25 18:05:12.183340>, <HistoricalChoice: Choice object as of 2010-10-25 18:04:59.047351>]
-