Improve documentation

CHANGES.rst

@@ -1,6 +1,28 @@
 Changelog for Charlatan
 =======================
 
+0.4.0 (unreleased)
+------------------
+
+- **Breaking change**: ``get_builder`` and ``delete_builder`` arguments were
+  added to :py:class:`charlatan.FixturesManager`.
+- **Breaking change**: ``delete_instance``, ``save_instance`` methods were
+  deleted in favor of using builders (see below).
+- **Breaking change**: ``fields`` argument on
+  :py:class:`charlatan.fixture.Fixture` and fixtures collection class has
+  been renamed ``overrides`` for consistency reasons.
+- **Breaking change**: deleting fixtures will not return anything. It used to
+  return the fixture or list of fixtures that were successfully deleted. It has
+  been removed to apply the command query separation pattern. There are other
+  ways to check which fixtures are installed, and hooks or builders can be used
+  to customize deletion.
+- **Breaking change**: ``do_not_save`` and ``do_not_delete`` arguments have
+  been removed from all functions, in favor of using builders.
+- The notion of :py:class:`charlatan.builder.Builder` was added. This allows
+  customizing how fixtures are instantiated and installed. A ``builder``
+  argument has been added to most method dealing with getting, installing or
+  deleting fixtures. Sane defaults have been added in most places.
+
 0.3.12 (2015-01-14)
 -------------------
 

charlatan/builder.py

@@ -10,6 +10,10 @@ def __call__(self, fixtures, klass, params, **kwargs):
         :param klass: the fixture's class (``model`` in the definition file)
         :param params: the fixture's params (``fields`` in the definition
             file)
+        :param dict kwargs:
+
+        ``kwargs`` allows passing arguments to the builder to change its
+        behavior.
         """
         raise NotImplementedError
 

charlatan/fixtures_manager.py

@@ -33,6 +33,13 @@ class FixturesManager(object):
     :param func get_builder:
     :param func delete_builder:
 
+    .. versionadded:: 0.4.0
+        ``get_builder`` and ``delete_builder`` arguments were added.
+
+    .. deprecated:: 0.4.0
+        ``delete_instance``, ``save_instance`` methods were deleted in favor
+        of using builders.
+
     .. versionadded:: 0.3.0
         ``db_session`` argument was added.
     """
@@ -397,6 +404,9 @@ def get_fixtures(self, fixture_keys, builder=None):
 
         :rtype: list of instantiated but unsaved fixtures
 
+        .. versionadded:: 0.4.0
+            ``builder`` argument was added.
+
         .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
         """
@@ -413,6 +423,9 @@ def get_all_fixtures(self, fixture_keys, builder=None):
 
         :rtype: list of instantiated but unsaved fixtures
 
+        .. versionadded:: 0.4.0
+            ``builder`` argument was added.
+
         .. deprecated:: 0.3.7
             ``include_relationships`` argument was removed.
         """

docs/builders.rst

@@ -8,7 +8,7 @@ your own builders and provide them as arguments when you instantiate
 Example
 -------
 
-Here's an example inspired by the schematics library, which expect a dict of
+Here's an example inspired by the schematics library, which expects a dict of
 attributes as a single instantiation argument:
 
 .. literalinclude:: ../charlatan/tests/example/test_custom_builder.py