Add some more documentation and a doctest on image creation

I struggled a bit when upgrading to testcontainers-rs 0.23, since the
interfaces had changed somewhat since the last version I used. The
documentation didn't explain exactly how to use the methods in `ImageExt`
in conjunction with those of `GenericImage`.

This change adds a bit more content to the documentation:

* A few more lines in the README file to exercise the configuration
  methods in `ImageExt`,
* Some documentation for `GenericImage` showing how it is used along with
  `ImageExt`.

The latter in particular includes a doctest. If the API is changed in the
future so that further changes are needed, the doctest will fail and can
be updated accordingly. This will make it easier for downstream users to
understand how to port their code.

README.md

@@ -22,13 +22,15 @@ The crate provides an API for working with containers in a test environment.
 - Blocking API (under `blocking` feature)
 
 ```rust
-use testcontainers::{core::{IntoContainerPort, WaitFor}, runners::SyncRunner, GenericImage};
+use testcontainers::{core::{IntoContainerPort, WaitFor}, runners::SyncRunner, GenericImage, ImageExt};
 
 #[test]
 fn test_redis() {
     let container = GenericImage::new("redis", "7.2.4")
         .with_exposed_port(6379.tcp())
         .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
+        .with_network("bridge")
+        .with_env_var("DEBUG", "1")
         .start()
         .expect("Redis started");
 }
@@ -37,13 +39,15 @@ fn test_redis() {
 - Async API
 
 ```rust
-use testcontainers::{core::{IntoContainerPort, WaitFor}, runners::AsyncRunner, GenericImage};
+use testcontainers::{core::{IntoContainerPort, WaitFor}, runners::AsyncRunner, GenericImage, ImageExt};
 
 #[tokio::test]
 async fn test_redis() {
     let container = GenericImage::new("redis", "7.2.4")
         .with_exposed_port(6379.tcp())
         .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
+        .with_network("bridge")
+        .with_env_var("DEBUG", "1")
         .start()
         .await
         .expect("Redis started");

testcontainers/src/images/generic.rs

@@ -3,6 +3,46 @@ use crate::{
     Image,
 };
 
+/// A configurable image from which a [`Container`] or [`ContainerAsync`] can be started.
+///
+/// The various methods on this struct allow for configuring the resulting container using the
+/// builder pattern. Further configuration is available through the [`ImageExt`] extension trait.
+/// Make sure to invoke the configuration methods on [`GenericImage`] first, before those from
+/// [`ImageExt`].
+///
+/// For example:
+///
+/// ```
+/// use testcontainers::{
+///     core::{IntoContainerPort, WaitFor}, runners::AsyncRunner, GenericImage, ImageExt
+/// };
+///
+/// # /*
+/// #[tokio::test]
+/// # */
+/// async fn test_redis() {
+///     let container = GenericImage::new("redis", "7.2.4")
+///         .with_exposed_port(6379.tcp())
+///         .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
+///         .with_network("bridge")
+///         .with_env_var("DEBUG", "1")
+///         .start()
+///         .await
+///         .expect("Redis started");
+/// #   container.stop().await.unwrap();
+/// }
+/// # let rt = tokio::runtime::Runtime::new().unwrap();
+/// # rt.block_on(test_redis());
+/// ```
+///
+/// The extension traits [`SyncRunner`] and [`AsyncRunner`] each provide the method `start()` to
+/// start the container once it is configured.
+///
+/// [`Container`]: crate::Container
+/// [`ContainerAsync`]: crate::ContainerAsync
+/// [`ImageExt`]: crate::core::ImageExt
+/// [`SyncRunner`]: crate::runners::SyncRunner
+/// [`AsyncRunner`]: crate::runners::AsyncRunner
 #[must_use]
 #[derive(Debug, Clone)]
 pub struct GenericImage {