Add docs for SubFactory.

Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>

2 files changed, 60 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 69b3b99..17d81c1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -54,9 +54,13 @@ Once defined, a factory can be instantiated through different methods::
 
 Contents:
 
+:doc:`SubFactory <subfactory>`
+
 .. toctree::
    :maxdepth: 2
 
+   subfactory
+
 Indices and tables
 ==================
 
diff --git a/docs/subfactory.rst b/docs/subfactory.rst
new file mode 100644
index 0000000..8bc1d8f
--- /dev/null
+++ b/docs/subfactory.rst
@@ -0,0 +1,56 @@
+SubFactory
+==========
+
+Some objects may use other complex objects as parameters; in order to simplify this setup, factory_boy
+provides the :py:class:`factory.SubFactory` class.
+
+This should be used when defining a :py:class:`~factory.Factory` attribute that will hold the other complex object::
+
+    import factory
+
+    # A standard factory
+    class UserFactory(factory.Factory):
+        FACTORY_FOR = User
+
+        # Various fields
+        first_name = 'John'
+        last_name = factory.Sequence(lambda n: 'D%se' % (o * n))
+        email = factory.LazyAttribute(lambda o: '%s.%s@example.org' % (o.first_name.lower(), o.last_name.lower()))
+
+    # A factory for an object with a 'User' field
+    class CompanyFactory(factory.Factory):
+        FACTORY_FOR = Company
+
+        name = factory.Sequence(lambda n: 'FactoryBoyz' + z * n)
+
+        # Let's use our UserFactory to create that user, and override its first name.
+        owner = factory.SubFactory(UserFactory, first_name='Jack')
+
+Instantiating the external factory will in turn instantiate an object of the internal factory::
+
+    >>> c = CompanyFactory()
+    >>> c
+    <Company: FactoryBoyz>
+
+    # Notice that the first_name was overridden
+    >>> c.owner
+    <User: Jack De>
+    >>> c.owner.email
+    jack.de@example.org
+
+Fields of the SubFactory can also be overridden when instantiating the external factory::
+
+    >>> c = CompanyFactory(owner__first_name='Henry')
+    >>> c.owner
+    <User: Henry Doe>
+
+    # Notice that the updated first_name was propagated to the email LazyAttribute.
+    >>> c.owner.email
+    henry.doe@example.org
+    
+    # It is also possible to override other fields of the SubFactory
+    >>> c = CompanyFactory(owner__last_name='Jones')
+    >>> c.owner
+    <User: Henry Jones>
+    >>> c.owner.email
+    henry.jones@example.org