docs: fix building images guide to use real DockerImage API (#1047)

## What

The `docs/features/building_images.md` guide documented a
`build_image()` function imported from `testcontainers.core.container`.
That function does not exist anywhere in the source — the entire page
was based on a non-existent API.

This rewrites the guide to use the actual public API, the `DockerImage`
context manager from `testcontainers.core.image`.

## Changes

- Use `DockerImage(...)` as a context manager together with
`DockerContainer(str(image))`.
- Correct argument names: `dockerfile_path` (was `dockerfile`),
`no_cache` (was `nocache`).
- Remove the non-existent `context` argument — the build context **is**
the `path` argument.
- Document the build inspection helpers (`short_id`, `get_logs`,
`get_wrapped_image`) and the `clean_up` behavior.
- Clarify that extra kwargs (`buildargs`, `target`, `platform`,
`labels`, `cache_from`) are forwarded to docker-py's `images.build`.

## Context

Dockerfile support requested in #83 is already implemented via
`DockerImage`; only the documentation was inaccurate. Relates to #83.

Docs-only change; no code or tests affected.

Author: Tranquility2

docs/features/building_images.md

@@ -4,113 +4,136 @@ Testcontainers-Python allows you to build Docker images from Dockerfiles during
 
 ## Basic Image Building
 
-The simplest way to build an image is using the `build_image` function:
+The simplest way to build an image is using the `DockerImage` class. It is a context manager that builds the image on entry and removes it on exit:
 
 ```python
-from testcontainers.core.container import build_image
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.image import DockerImage
 
-# Build an image from a Dockerfile
-image = build_image(
-    path="path/to/dockerfile/directory",
-    tag="myapp:test"
-)
-
-# Use the built image
-with GenericContainer(image) as container:
-    # Your test code here
-    pass
+# Build an image from a build context containing a Dockerfile
+with DockerImage(path="path/to/dockerfile/directory", tag="myapp:test") as image:
+    # Use the built image
+    with DockerContainer(str(image)) as container:
+        # Your test code here
+        pass
 ```
 
-## Building with Options
+`path` is the build context directory. By default the Dockerfile is expected to be named `Dockerfile` within that directory.
 
-You can customize the build process with various options:
+## Building with a Custom Dockerfile
+
+Use `dockerfile_path` to point at a Dockerfile with a different name or location (relative to the build context):
 
 ```python
-# Build with specific Dockerfile
-image = build_image(
+with DockerImage(
     path="path/to/dockerfile/directory",
-    dockerfile="Dockerfile.test",
-    tag="myapp:test"
-)
+    dockerfile_path="Dockerfile.test",
+    tag="myapp:test",
+) as image:
+    ...
+```
+
+## Building with Options
+
+Any additional keyword arguments are forwarded to the underlying docker-py
+[`images.build`](https://docker-py.readthedocs.io/en/stable/images.html#docker.models.images.ImageCollection.build)
+call, so you can use all of its options.
 
-# Build with build arguments
-image = build_image(
+### Build Arguments
+
+```python
+with DockerImage(
     path="path/to/dockerfile/directory",
+    tag="myapp:test",
     buildargs={
         "VERSION": "1.0.0",
-        "ENVIRONMENT": "test"
+        "ENVIRONMENT": "test",
     },
-    tag="myapp:test"
-)
+) as image:
+    ...
+```
 
-# Build with target stage
-image = build_image(
+### Target Stage
+
+```python
+with DockerImage(
     path="path/to/dockerfile/directory",
+    tag="myapp:test",
     target="test",
-    tag="myapp:test"
-)
+) as image:
+    ...
 ```
 
-## Building with Context
+### Disabling the Build Cache
 
-You can specify a build context:
+Use the `no_cache` argument to bypass the build cache (equivalent to the CLI's `--no-cache`):
 
 ```python
-# Build with specific context
-image = build_image(
+with DockerImage(
     path="path/to/dockerfile/directory",
-    context="path/to/build/context",
-    tag="myapp:test"
-)
+    tag="myapp:test",
+    no_cache=True,
+) as image:
+    ...
 ```
 
-## Building with Cache
-
-You can control build caching:
+You can also reuse cache layers from existing images with `cache_from`:
 
 ```python
-# Build without cache
-image = build_image(
-    path="path/to/dockerfile/directory",
-    nocache=True,
-    tag="myapp:test"
-)
-
-# Build with specific cache from
-image = build_image(
+with DockerImage(
     path="path/to/dockerfile/directory",
+    tag="myapp:test",
     cache_from=["myapp:latest"],
-    tag="myapp:test"
-)
+) as image:
+    ...
 ```
 
-## Building with Platform
-
-You can specify the target platform:
+### Platform
 
 ```python
-# Build for specific platform
-image = build_image(
+with DockerImage(
     path="path/to/dockerfile/directory",
+    tag="myapp:test",
     platform="linux/amd64",
-    tag="myapp:test"
-)
+) as image:
+    ...
 ```
 
-## Building with Labels
-
-You can add labels to the built image:
+### Labels
 
 ```python
-# Build with labels
-image = build_image(
+with DockerImage(
     path="path/to/dockerfile/directory",
+    tag="myapp:test",
     labels={
         "test": "true",
-        "environment": "test"
+        "environment": "test",
     },
-    tag="myapp:test"
-)
+) as image:
+    ...
+```
+
+## Inspecting the Build
+
+`DockerImage` exposes helpers to inspect the result of a build:
+
+```python
+with DockerImage(path="path/to/dockerfile/directory", tag="myapp:test") as image:
+    print(image.short_id)        # short image ID
+    print(str(image))            # tag if set, otherwise short ID
+    logs = image.get_logs()      # list of build log entries
+    wrapped = image.get_wrapped_image()  # underlying docker-py Image
+```
+
+## Cleaning Up
+
+By default the image is removed when the context manager exits. Set `clean_up=False`
+to keep the image after the block completes:
+
+```python
+with DockerImage(path="path/to/dockerfile/directory", tag="myapp:test", clean_up=False) as image:
+    ...
+# image is still available here
 ```
 
 ## Best Practices
@@ -120,71 +143,50 @@ image = build_image(
 3. Use build arguments for configuration
 4. Consider build context size
 5. Use appropriate build caching
-6. Handle build failures
-7. Use appropriate platforms
-8. Add meaningful labels
+6. Use appropriate platforms
+7. Add meaningful labels
 
 ## Common Use Cases
 
 ### Building Test Images
 
 ```python
 def test_custom_image():
-    # Build test image
-    image = build_image(
+    with DockerImage(
         path="path/to/dockerfile/directory",
+        tag="myapp:test",
         buildargs={"TEST_MODE": "true"},
-        tag="myapp:test"
-    )
-
-    # Use the test image
-    with GenericContainer(image) as container:
-        # Your test code here
-        pass
-```
-
-### Building with Dependencies
-
-```python
-def test_with_dependencies():
-    # Build base image
-    base_image = build_image(
-        path="path/to/base/dockerfile/directory",
-        tag="myapp:base"
-    )
-
-    # Build test image using base
-    test_image = build_image(
-        path="path/to/test/dockerfile/directory",
-        cache_from=[base_image],
-        tag="myapp:test"
-    )
+    ) as image:
+        with DockerContainer(str(image)) as container:
+            # Your test code here
+            pass
 ```
 
 ### Building for Different Environments
 
 ```python
 def test_different_environments():
-    # Build for different environments
     environments = ["dev", "test", "staging"]
 
     for env in environments:
-        image = build_image(
+        with DockerImage(
             path="path/to/dockerfile/directory",
+            tag=f"myapp:{env}",
             buildargs={"ENVIRONMENT": env},
-            tag=f"myapp:{env}"
-        )
+        ) as image:
+            with DockerContainer(str(image)) as container:
+                # Your test code here
+                pass
 ```
 
 ## Troubleshooting
 
 If you encounter issues with image building:
 
 1. Check Dockerfile syntax
-2. Verify build context
+2. Verify the build context (the `path` argument)
 3. Check for missing files
 4. Verify build arguments
 5. Check for platform compatibility
 6. Verify cache settings
-7. Check for resource limits
-8. Verify Docker daemon state
+7. Verify Docker daemon state