Merge pull request #59 from ajdavis/document-process-image

Document process_image().

content/docs/api/utils/process-image/contents.lr

@@ -0,0 +1,45 @@
+title: process_image
+---
+module: lektor.imagetools
+---
+signature: ctx, source_image, dst_filename, width, height=None
+---
+summary: Build an image from a source image, optionally compressing and resizing.
+---
+type: function
+---
+version_added: 2.0
+---
+body:
+
+This function takes a [Context :ref](../../build/context/) object, the absolute paths to the image's source and target files, and the target image's width. If height is `None`, it is calculated from the source image width and the target width so that the image is scaled proportionally.
+
+Used internally for the implementation of [thumbnail :ref](../../db/record/thumbnail), and exposed as an API for image-processing plugins.
+
+## Example
+
+```python
+from lektor.build_programs import AttachmentBuildProgram
+from lektor.context import get_ctx
+from lektor.db import Image
+from lektor.imagetools import process_image
+from lektor.pluginsystem import Plugin
+
+
+class ResizeBuildProgram(AttachmentBuildProgram):
+    def build_artifact(self, artifact):
+        ctx = get_ctx()
+        width = 1024
+        source_img = artifact.source_obj.attachment_filename
+        artifact.ensure_dir()
+
+        process_image(ctx,
+                      source_img,
+                      artifact.dst_filename,
+                      width)
+
+
+class ImageResizePlugin(Plugin):
+    def on_setup_env(self, **extra):
+        self.env.add_build_program(Image, ResizeBuildProgram)
+```