1 files changed, 84 insertions, 13 deletions
diff --git a/docs/orms.rst b/docs/orms.rst
index e50e706..2aa27b2 100644
--- a/docs/orms.rst
+++ b/docs/orms.rst
@@ -32,7 +32,7 @@ All factories for a Django :class:`~django.db.models.Model` should use the
 
     This class provides the following features:
 
-    * The :attr:`~factory.Factory.FACTORY_FOR` attribute also supports the ``'app.Model'``
+    * The :attr:`~factory.FactoryOptions.model` attribute also supports the ``'app.Model'``
       syntax
     * :func:`~factory.Factory.create()` uses :meth:`Model.objects.create() <django.db.models.query.QuerySet.create>`
     * :func:`~factory.Factory._setup_next_sequence()` selects the next unused primary key value
@@ -42,6 +42,18 @@ All factories for a Django :class:`~django.db.models.Model` should use the
 
     .. attribute:: FACTORY_DJANGO_GET_OR_CREATE
 
+        .. deprecated:: 2.4.0
+                        See :attr:`DjangoOptions.django_get_or_create`.
+
+
+.. class:: DjangoOptions(factory.base.FactoryOptions)
+
+    The ``class Meta`` on a :class:`~DjangoModelFactory` supports an extra parameter:
+
+    .. attribute:: django_get_or_create
+
+        .. versionadded:: 2.4.0
+
         Fields whose name are passed in this list will be used to perform a
         :meth:`Model.objects.get_or_create() <django.db.models.query.QuerySet.get_or_create>`
         instead of the usual :meth:`Model.objects.create() <django.db.models.query.QuerySet.create>`:
@@ -49,8 +61,9 @@ All factories for a Django :class:`~django.db.models.Model` should use the
         .. code-block:: python
 
             class UserFactory(factory.django.DjangoModelFactory):
-                FACTORY_FOR = 'myapp.User'  # Equivalent to ``FACTORY_FOR = myapp.models.User``
-                FACTORY_DJANGO_GET_OR_CREATE = ('username',)
+                class Meta:
+                    model = 'myapp.User'  # Equivalent to ``model = myapp.models.User``
+                    django_get_or_create = ('username',)
 
                 username = 'john'
 
@@ -80,15 +93,21 @@ All factories for a Django :class:`~django.db.models.Model` should use the
           .. code-block:: python
 
               class MyAbstractModelFactory(factory.django.DjangoModelFactory):
-                  FACTORY_FOR = models.MyAbstractModel
-                  ABSTRACT_FACTORY = True
+                  class Meta:
+                      model = models.MyAbstractModel
+                      abstract = True
 
               class MyConcreteModelFactory(MyAbstractModelFactory):
-                  FACTORY_FOR = models.MyConcreteModel
+                  class Meta:
+                      model = models.MyConcreteModel
 
           Otherwise, factory_boy will try to get the 'next PK' counter from the abstract model.
 
 
+Extra fields
+""""""""""""
+
+
 .. class:: FileField
 
     Custom declarations for :class:`django.db.models.FileField`
@@ -108,7 +127,8 @@ All factories for a Django :class:`~django.db.models.Model` should use the
 .. code-block:: python
 
     class MyFactory(factory.django.DjangoModelFactory):
-        FACTORY_FOR = models.MyModel
+        class Meta:
+            model = models.MyModel
 
         the_file = factory.django.FileField(filename='the_file.dat')
 
@@ -145,7 +165,8 @@ All factories for a Django :class:`~django.db.models.Model` should use the
 .. code-block:: python
 
     class MyFactory(factory.django.DjangoModelFactory):
-        FACTORY_FOR = models.MyModel
+        class Meta:
+            model = models.MyModel
 
         the_image = factory.django.ImageField(color='blue')
 
@@ -157,6 +178,44 @@ All factories for a Django :class:`~django.db.models.Model` should use the
     None
 
 
+Disabling signals
+"""""""""""""""""
+
+Signals are often used to plug some custom code into external components code;
+for instance to create ``Profile`` objects on-the-fly when a new ``User`` object is saved.
+
+This may interfere with finely tuned :class:`factories <DjangoModelFactory>`, which would
+create both using :class:`~factory.RelatedFactory`.
+
+To work around this problem, use the :meth:`mute_signals()` decorator/context manager:
+
+.. method:: mute_signals(signal1, ...)
+
+    Disable the list of selected signals when calling the factory, and reactivate them upon leaving.
+
+.. code-block:: python
+
+    # foo/factories.py
+
+    import factory
+    import factory.django
+
+    from . import models
+    from . import signals
+
+    @factory.django.mute_signals(signals.pre_save, signals.post_save)
+    class FooFactory(factory.django.DjangoModelFactory):
+        class Meta:
+            model = models.Foo
+
+        # ...
+
+    def make_chain():
+        with factory.django.mute_signals(signals.pre_save, signals.post_save):
+            # pre_save/post_save won't be called here.
+            return SomeFactory(), SomeOtherFactory()
+
+
 Mogo
 ----
 
@@ -200,7 +259,7 @@ factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngin
     * :func:`~factory.Factory.create()` builds an instance through ``__init__`` then
       saves it.
 
-    .. note:: If the :attr:`associated class <factory.Factory.FACTORY_FOR>` is a :class:`mongoengine.EmbeddedDocument`,
+    .. note:: If the :attr:`associated class <factory.FactoryOptions.model` is a :class:`mongoengine.EmbeddedDocument`,
               the :meth:`~MongoEngineFactory.create` function won't "save" it, since this wouldn't make sense.
 
               This feature makes it possible to use :class:`~factory.SubFactory` to create embedded document.
@@ -214,7 +273,7 @@ SQLAlchemy
 
 Factoy_boy also supports `SQLAlchemy`_  models through the :class:`SQLAlchemyModelFactory` class.
 
-To work, this class needs an `SQLAlchemy`_ session object affected to "FACTORY_SESSION" class attribute.
+To work, this class needs an `SQLAlchemy`_ session object affected to the :attr:`Meta.sqlalchemy_session <SQLAlchemyOptions.sqlalchemy_session>` attribute.
 
 .. _SQLAlchemy: http://www.sqlalchemy.org/
 
@@ -229,7 +288,18 @@ To work, this class needs an `SQLAlchemy`_ session object affected to "FACTORY_S
 
     .. attribute:: FACTORY_SESSION
 
-        Fields whose SQLAlchemy session object are passed will be used to communicate with the database
+        .. deprecated:: 2.4.0
+                        See :attr:`~SQLAlchemyOptions.sqlalchemy_session`.
+
+.. class:: SQLAlchemyOptions(factory.base.FactoryOptions)
+
+    In addition to the usual parameters available in :class:`class Meta <factory.base.FactoryOptions>`,
+    a :class:`SQLAlchemyModelFactory` also supports the following settings:
+
+    .. attribute:: sqlalchemy_session
+
+        SQLAlchemy session to use to communicate with the database when creating
+        an object through this :class:`SQLAlchemyModelFactory`.
 
 A (very) simple exemple:
 
@@ -256,8 +326,9 @@ A (very) simple exemple:
 
 
     class UserFactory(SQLAlchemyModelFactory):
-        FACTORY_FOR = User
-        FACTORY_SESSION = session   # the SQLAlchemy session object
+        class Meta:
+            model = User
+            sqlalchemy_session = session   # the SQLAlchemy session object
 
         id = factory.Sequence(lambda n: n)
         name = factory.Sequence(lambda n: u'User %d' % n)