Improve documentation

src/auditlog/diff.py

@@ -7,8 +7,8 @@ from django.utils.encoding import smart_text
 
 def model_instance_diff(old, new):
     """
-    Calculates the differences between two model instances. One of the instances may be None (i.e., a newly
-    created model or deleted model). This will cause all fields with a value to have changed (from None).
+    Calculates the differences between two model instances. One of the instances may be ``None`` (i.e., a newly
+    created model or deleted model). This will cause all fields with a value to have changed (from ``None``).
 
     :param old: The old state of the model instance.
     :type old: Model
@@ -16,7 +16,7 @@ def model_instance_diff(old, new):
     :type new: Model
     :return: A dictionary with the names of the changed fields as keys and a two tuple of the old and new field values
              as value.
-    :rtype: {str: (str|None, str|None)}
+    :rtype: dict
     """
     from auditlog.registry import auditlog
 

src/auditlog/models.py

@@ -13,13 +13,19 @@ from django.utils.translation import ugettext_lazy as _
 
 class LogEntryManager(models.Manager):
     """
-    Custom manager for the LogEntry model.
+    Custom manager for the :py:class:`LogEntry` model.
     """
 
     def log_create(self, instance, **kwargs):
         """
-        Helper method to create a new log entry. This method automatically fills in some data when it is left out. It
-        was created to keep things DRY.
+        Helper method to create a new log entry. This method automatically populates some fields when no explicit value
+        is given.
+
+        :param instance: The model instance to log a change for.
+        :type instance: Model
+        :param kwargs: Field overrides for the :py:class:`LogEntry` object.
+        :return: The new log entry or `None` if there were no changes.
+        :rtype: LogEntry
         """
         changes = kwargs.get('changes', None)
         pk = self._get_pk_value(instance)
@@ -46,6 +52,11 @@ class LogEntryManager(models.Manager):
     def get_for_object(self, instance):
         """
         Get log entries for the specified model instance.
+
+        :param instance: The model instance to get log entries for.
+        :type instance: Model
+        :return: QuerySet of log entries for the given model instance.
+        :rtype: QuerySet
         """
         # Return empty queryset if the given model instance is not a model instance.
         if not isinstance(instance, models.Model):
@@ -62,6 +73,11 @@ class LogEntryManager(models.Manager):
     def get_for_model(self, model):
         """
         Get log entries for all objects of a specified type.
+
+        :param model: The model to get log entries for.
+        :type model: class
+        :return: QuerySet of log entries for the given model.
+        :rtype: QuerySet
         """
         # Return empty queryset if the given object is not valid.
         if not issubclass(model, models.Model):
@@ -74,6 +90,10 @@ class LogEntryManager(models.Manager):
     def _get_pk_value(self, instance):
         """
         Get the primary key field value for a model instance.
+
+        :param instance: The model instance to get the primary key for.
+        :type instance: Model
+        :return: The primary key value of the given model instance.
         """
         pk_field = instance._meta.pk.name
         pk = getattr(instance, pk_field, None)
@@ -100,7 +120,10 @@ class LogEntry(models.Model):
         """
         The actions that Auditlog distinguishes: creating, updating and deleting objects. Viewing objects is not logged.
         The values of the actions are numeric, a higher integer value means a more intrusive action. This may be useful
-        in some cases when comparing actions because __lt, __lte, __gt, __gte can be used in queries.
+        in some cases when comparing actions because the ``__lt``, ``__lte``, ``__gt``, ``__gte`` lookup filters can be
+        used in queries.
+
+        The valid actions are :py:attr:`Action.CREATE`, :py:attr:`Action.UPDATE` and :py:attr:`Action.DELETE`.
         """
         CREATE = 0
         UPDATE = 1
@@ -156,7 +179,7 @@ class LogEntry(models.Model):
         """
         Return the changes recorded in this log entry as a string. The formatting of the string can be customized by
         setting alternate values for colon, arrow and separator. If the formatting is still not satisfying, please use
-        changes_dict() and format the string yourself.
+        :py:func:`LogEntry.changes_dict` and format the string yourself.
 
         :param colon: The string to place between the field name and the values.
         :param arrow: The string to place between each old and new value.
@@ -180,22 +203,21 @@ class LogEntry(models.Model):
 
 class AuditlogHistoryField(generic.GenericRelation):
     """
-    A subclass of django.contrib.contenttypes.generic.GenericRelation that sets some default variables. This makes it
-    easier to implement the audit log in models, and makes future changes easier.
+    A subclass of py:class:`django.contrib.contenttypes.generic.GenericRelation` that sets some default variables. This
+    makes it easier to access Auditlog's log entries, for example in templates.
 
     By default this field will assume that your primary keys are numeric, simply because this is the most common case.
-    However, if you have a non-integer primary key, you can simply pass pk_indexable=False to the constructor, and
+    However, if you have a non-integer primary key, you can simply pass ``pk_indexable=False`` to the constructor, and
     Auditlog will fall back to using a non-indexed text based field for this model.
 
     Using this field will not automatically register the model for automatic logging. This is done so you can be more
     flexible with how you use this field.
+
+    :param pk_indexable: Whether the primary key for this model is not an :py:class:`int` or :py:class:`long`.
+    :type pk_indexable: bool
     """
 
     def __init__(self, pk_indexable=True, **kwargs):
-        """
-        :param pk_indexable: Whether the primary key for this model is not an integer or long.
-        :type pk_indexable: bool
-        """
         kwargs['to'] = LogEntry
 
         if pk_indexable:

src/auditlog/receivers.py

@@ -10,7 +10,7 @@ def log_create(sender, instance, created, **kwargs):
     """
     Signal receiver that creates a log entry when a model instance is first saved to the database.
 
-    Direct use is discouraged, connect your model through auditlog.registry.register instead.
+    Direct use is discouraged, connect your model through :py:func:`auditlog.registry.register` instead.
     """
     if created:
         changes = model_instance_diff(None, instance)
@@ -26,7 +26,7 @@ def log_update(sender, instance, **kwargs):
     """
     Signal receiver that creates a log entry when a model instance is changed and saved to the database.
 
-    Direct use is discouraged, connect your model through auditlog.registry.register instead.
+    Direct use is discouraged, connect your model through :py:func:`auditlog.registry.register` instead.
     """
     if instance.pk is not None:
         try:
@@ -51,7 +51,7 @@ def log_delete(sender, instance, **kwargs):
     """
     Signal receiver that creates a log entry when a model instance is deleted from the database.
 
-    Direct use is discouraged, connect your model through auditlog.registry.register instead.
+    Direct use is discouraged, connect your model through :py:func:`auditlog.registry.register` instead.
     """
     if instance.pk is not None:
         changes = model_instance_diff(instance, None)

src/auditlog/registry.py

@@ -31,9 +31,9 @@ class AuditlogModelRegistry(object):
         :param model: The model to register.
         :type model: Model
         :param include_fields: The fields to include. Implicitly excludes all other fields.
-        :type include_fields: [str]
+        :type include_fields: list
         :param exclude_fields: The fields to exclude. Overrides the fields to include.
-        :type exclude_fields: [str]
+        :type exclude_fields: list
         """
         if issubclass(model, Model):
             self._registry[model] = {