accompanying documentation updates to lektor/#551

content/docs/api/db/record/thumbnail/contents.lr

@@ -4,7 +4,7 @@ summary: Creates a thumbnail for an image.
 ---
 type: method
 ---
-signature: width, height=None, crop=False, quality=None
+signature: width=None, height=None, mode=None, upscale=None, quality=None
 ---
 body:
 
@@ -12,10 +12,25 @@ This method is available on attachments that are images and can be used to
 automatically generate a thumbnail.  The return value is a thumbnail proxy
 that can be either used directly or with the `|url` filter.
 
-If cropping is not enabled the thumbnail is scaled down to fit into the
-given reactangle of width and height.  If height is not specified it will
-match the width and the height is set accordingly.  If cropping is enabled
-it's cropped around the edges to fit into the center.
+The outcome differs depending on the operation mode, which can be one of "fit"
+(the default), "crop" or "stretch".
+
+In "fit" mode, the thumbnail is scaled to fit into the rectangle of given
+width and height. If either dimension is `None`, it will be computed to match
+the other one accordingly.
+
+In "crop" mode, width and height are both required. The image is scaled
+to cover the given rectangle, center-aligned, and then cropped so that
+anything outside those bounds gets trimmed.
+
+In "stretch" mode, the image is resized precisely to the required dimensions,
+so the original proportions are not preserved. Most of the time this is not
+what you want.
+
+By setting the `upscale` parameter to `False` you can prevent the images
+from being scaled up if the resulting thumbnail would be larger than the original
+image. In this case the original is returned instead.
+(Note that in a future version this will be the default in "fit" mode.)
 
 The quality parameter determines the compression of images where possible. If not passed the jpeg images get a default quality of 85 and png images get a default quality of 75.
 
@@ -26,9 +41,6 @@ It provides the following attributes:
 * `url_path` the URL path of the thumbnail.  This is absolute and needs to
   be made relative with the `|url` filter.
 
-!!! Starting with Lektor 2.0 you can also pass `crop=True` to crop the image
-to the exact dimensions provided instead of scaling it uncropped.
-
 ## Example
 
 ```html+jinja
@@ -38,5 +50,11 @@ to the exact dimensions provided instead of scaling it uncropped.
 ```
 
 ```html+jinja
-<img src="{{ image.thumbnail(1920, 1080, crop=True, quality=40)|url }}">
+{% for image in this.attachments.images %}
+  <img src="{{ image.thumbnail(height=64)|url }}">
+{% endfor %}
+```
+
+```html+jinja
+<img src="{{ image.thumbnail(1920, 1080, mode="crop", quality=40)|url }}">
 ```

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

@@ -2,7 +2,7 @@ title: process_image
 ---
 module: lektor.imagetools
 ---
-signature: ctx, source_image, dst_filename, width, height=None
+signature: ctx, source_image, dst_filename, width=None, height=None, mode=ThumbnailMode.DEFAULT
 ---
 summary: Build an image from a source image, optionally compressing and resizing.
 ---
@@ -12,7 +12,11 @@ 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.
+This function takes a [Context :ref](../../build/context/) object, the
+absolute paths to the image's source and target files, the target image's
+width and/or height, and the operation mode.
+In the default mode, if width or height are `None`, they are calculated
+from the source image's dimensions 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.
 
@@ -22,24 +26,24 @@ Used internally for the implementation of [thumbnail :ref](../../db/record/thumb
 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.imagetools import process_image, ThumbnailMode
 from lektor.pluginsystem import Plugin
 
 
-class ResizeBuildProgram(AttachmentBuildProgram):
+class ImageCropBuildProgram(AttachmentBuildProgram):
     def build_artifact(self, artifact):
         ctx = get_ctx()
-        width = 1024
+        width, height = 600, 400
         source_img = artifact.source_obj.attachment_filename
         artifact.ensure_dir()
 
         process_image(ctx,
                       source_img,
                       artifact.dst_filename,
-                      width)
+                      width, height, mode=ThumbnailMode.CROP)
 
 
-class ImageResizePlugin(Plugin):
+class ImageCropPlugin(Plugin):
     def on_setup_env(self, **extra):
-        self.env.add_build_program(Image, ResizeBuildProgram)
+        self.env.add_build_program(Image, ImageCropBuildProgram)
 ```

content/docs/templates/imageops/contents.lr

@@ -81,8 +81,8 @@ still need to transmit the entire image.  When you want smaller images it
 often makes sense to generate thumbnails automatically.  In Lektor each
 image provides the [thumbnail :ref](../../api/db/record/thumbnail/) method.
 
-It accepts the width and height of the target image.  If the height is not
-provided it will be scaled proportionally.  The return value can be converted
+It accepts the width and height of the target image. If either of these is not
+provided, it will be computed automatically. The return value can be converted
 into a URL with the `|url` filter:
 
 ```html+jinja