More advanced docs!

docs/advanced_usage/optimizing.rst

@@ -41,8 +41,58 @@ called *generated file strategies*. The default strategy can be set using the
 ``IMAGEKIT_DEFAULT_GENERATEDFILE_STRATEGY`` setting, and its default value is
 `'imagekit.generatedfiles.strategies.JustInTime'`. As we've already seen above,
 the "just in time" strategy determines whether a file needs to be generated each
-time it's accessed and, if it does, generates it synchronously.
+time it's accessed and, if it does, generates it synchronously (that is, as part
+of the request-response cycle).
+
+Another strategy is to simply assume the file exists. This requires the fewest
+number of checks (zero!), so we don't have to worry about expensive IO. The
+strategy that takes this approach is
+``imagekit.generatedfiles.strategies.Optimistic``. In order to use this
+strategy, either set the ``IMAGEKIT_DEFAULT_GENERATEDFILE_STRATEGY`` setting or,
+to use it on a per-generator basis, set the ``generatedfile_strategy`` attribute
+of your spec or generator. Avoiding checking for file existence can be a real
+boon to performance, but it also means that ImageKit has no way to know when a
+file needs to be generated—well, at least not all the time.
+
+With image specs, we can know at least some of the times that a new file needs
+to be generated: whenever the source image is created or changed. For this
+reason, the optimistic strategy defines callbacks for these events. Every
+`source registered with ImageKit`__ will automatically cause its specs' files to
+be generated when it is created or changed.
+
+.. note::
+
+    In order to understand source registration, read :ref:`source-groups`
+
+If you have specs that `change based on attributes of the source`__, that's not
+going to cut it, though; the file will also need to be generated when those
+attributes change. Likewise, image generators that don't have sources (i.e.
+generators that aren't specs) won't cause files to be generated automatically
+when using the optimistic strategy. (ImageKit can't know when those need to be
+generated, if not on access.) In both cases, you'll have to trigger the file
+generation yourself—either by generating the file in code when necessary, or by
+periodically running the ``generateimages`` management command. Luckily,
+ImageKit makes this pretty easy:
+
+.. code-block:: python
+
+    from imagekit.generatedfiles import LazyGeneratedImageFile
+
+    file = LazyGeneratedImageFile('myapp:profile:avatar_thumbnail', source=source_file)
+    file.generate()
+
+One final situation in which images won't be generated automatically when using
+the optimistic strategy is when you use a spec with a source that hasn't been
+registered with it. Unlike the previous two examples, this situation cannot be
+rectified by running the ``generateimages`` management command, for the simple
+reason that the command has no way of knowing it needs to generate a file for
+that spec from that source. Typically, this situation would arise when using the
+template tags. Unlike ImageSpecFields, which automatically register all the
+possible source images with the spec you define, the template tags
+("generateimage" and "thumbnail") let you use any spec with any source.
 
 
 
 __ https://docs.djangoproject.com/en/dev/ref/files/storage/
+__
+__

docs/advanced_usage/source_groups.rst

@@ -0,0 +1,24 @@
+.. _source-groups:
+
+ImageKit allows you to register objects—called *source groups*—which do two
+things: 1) dispatch signals when a source is created, changed, or deleted, and
+2) expose a generator method that enumerates source files. When these objects
+are registered (using ``imagekit.register.source_group()``), their signals will
+trigger callbacks on the generated file strategies associated with image specs
+that use the source. In addition, the generator method is used (indirectly) to
+create the list of files to generate with the ``generateimages`` management
+command.
+
+Currently, there is only one source group class bundled with ImageKit,
+``imagekit.specs.sourcegroups.ImageFieldSourceGroup``, which represents an
+ImageField on every instance of a particular model. In terms of the above
+description, ``ImageFieldSourceGroup(Profile, 'avatar')`` 1) dispatches a signal
+every time the image in Profile's avatar ImageField changes, and 2) exposes a
+generator method that iterates over every Profile's "avatar" image.
+
+ImageKit automatically creates and registers an instance of
+ImageFieldSourceGroup every time you create an ImageSpecField; that's how the
+field is connected (internally) to the spec you're defining, and therefore to
+the generated file strategy responsible for generating the file. It's also how
+the ``generateimages`` management command is able to know which sources to
+generate files for.