Initial docs for EntityProxyFields.

diff --git a/docs/models/fields.rst b/docs/models/fields.rst
new file mode 100644 (file)
index 0000000..91164a3
--- /dev/null
+++ b/docs/models/fields.rst
@@ -0,0 +1,11 @@
+Custom Fields
+=============
+
+.. automodule:: philo.models.fields
+       :members:
+
+EntityProxyFields
+=================
+
+.. automodule:: philo.models.fields.entities
+       :members:
\ No newline at end of file

diff --git a/docs/models/intro.rst b/docs/models/intro.rst
index 7efec7f..4f65585 100644 (file)
--- a/docs/models/intro.rst
+++ b/docs/models/intro.rst
@@ -10,6 +10,7 @@ Contents:
    nodes-and-views
    collections
    miscellaneous
+   fields
 
 
 .. automodule:: philo.models

diff --git a/docs/models/miscellaneous.rst b/docs/models/miscellaneous.rst
index dfff87e..ea13db2 100644 (file)
--- a/docs/models/miscellaneous.rst
+++ b/docs/models/miscellaneous.rst
@@ -1,4 +1,4 @@
-Miscellaneous Support Models
+Miscellaneous Models
 =============================
 .. currentmodule:: philo.models.nodes
 .. autoclass:: philo.models.nodes.TargetURLModel

diff --git a/philo/models/fields/entities.py b/philo/models/fields/entities.py
index 68a4164..c37d496 100644 (file)
--- a/philo/models/fields/entities.py
+++ b/philo/models/fields/entities.py
@@ -1,18 +1,10 @@
 """
-The EntityProxyFields defined in this file can be assigned as fields on
-a subclass of philo.models.Entity. They act like any other model
-fields, but instead of saving their data to the database, they save it
-to attributes related to a model instance. Additionally, a new
-attribute will be created for an instance if and only if the field's
-value has been set. This is relevant i.e. for passthroughs, where the
-value of the field may be defined by some other instance's attributes.
+EntityProxyFields can be assigned as fields on a subclass of philo.models.Entity. They act like any other model fields, but instead of saving their data to the model's table, they save it to attributes related to a model instance. Additionally, a new attribute will be created for an instance if and only if the field's value has been set. This is relevant i.e. for :class:`QuerySetMapper` passthroughs, where even an Attribute with a value of ``None`` must prevent a passthrough.
 
 Example::
 
        class Thing(Entity):
                numbers = models.PositiveIntegerField()
-       
-       class ThingProxy(Thing):
                improvised = JSONAttribute(models.BooleanField)
 """
 import datetime
@@ -126,6 +118,7 @@ class AttributeFieldDescriptor(object):
 
 
 def process_attribute_fields(sender, instance, created, **kwargs):
+       """This function is attached to each :class:`Entity` subclass's post_save signal. Any :class:`Attribute`\ s managed by EntityProxyFields which have been removed will be deleted, and any new attributes will be created """
        if ATTRIBUTE_REGISTRY in instance.__dict__:
                registry = instance.__dict__[ATTRIBUTE_REGISTRY]
                instance.attribute_set.filter(key__in=[field.attribute_key for field in registry['removed']]).delete()
@@ -182,6 +175,8 @@ class AttributeField(EntityProxyField):
 
 
 class JSONAttribute(AttributeField):
+       """Handles an :class:`Attribute` with a :class:`JSONValue`."""
+       
        value_class = JSONValue
        
        def __init__(self, field_template=None, **kwargs):
@@ -216,6 +211,7 @@ class JSONAttribute(AttributeField):
 
 
 class ForeignKeyAttribute(AttributeField):
+       """Handles an :class:`Attribute` with a :class:`ForeignKeyValue`."""
        value_class = ForeignKeyValue
        
        def __init__(self, model, limit_choices_to=None, **kwargs):