docs: add readme to crates.io and fix documentation builds (#598)

testcontainers/Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "testcontainers"
 version = "0.16.0"
-authors.workspace = true
 categories = ["development-tools::testing"]
+readme = "README.md"
+authors.workspace = true
 edition.workspace = true
 keywords.workspace = true
 license.workspace = true

testcontainers/README.md

@@ -0,0 +1,66 @@
+# Testcontainers-rs
+
+![Continuous Integration](https://github.com/testcontainers/testcontainers-rs/workflows/Continuous%20Integration/badge.svg?branch=main)
+[![Crates.io](https://img.shields.io/crates/v/testcontainers.svg)](https://crates.io/crates/testcontainers)
+[![Docs.rs](https://docs.rs/testcontainers/badge.svg)](https://docs.rs/testcontainers)
+[![Slack](https://img.shields.io/badge/Slack-join-orange?style=flat&logo=slack&)](https://join.slack.com/t/testcontainers/shared_invite/zt-2gra37tid-n9xDJGjjVb7hMRanGjowkw)
+
+Testcontainers-rs is the official Rust language fork of [http://testcontainers.org](http://testcontainers.org).
+
+## Usage
+
+### `testcontainers` is the core crate
+
+The crate provides an API for working with containers in a test environment.
+
+1. Depend on `testcontainers`
+2. Implement `testcontainers::core::Image` for necessary docker-images
+3. Run it with any available runner `testcontainers::runners::*` (use `blocking` feature for synchronous API)
+
+#### Example:
+
+- Blocking API (under `blocking` feature)
+
+```rust
+use testcontainers::{core::WaitFor, runners::SyncRunner, GenericImage};
+
+#[test]
+fn test_redis() {
+    let container = GenericImage::new("redis", "7.2.4")
+        .with_exposed_port(6379)
+        .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
+        .start();
+}
+```
+
+- Async API
+
+```rust
+use testcontainers::{core::WaitFor, runners::AsyncRunner, GenericImage};
+
+#[tokio::test]
+async fn test_redis() {
+    let container = GenericImage::new("redis", "7.2.4")
+        .with_exposed_port(6379)
+        .with_wait_for(WaitFor::message_on_stdout("Ready to accept connections"))
+        .start()
+        .await;
+}
+```
+
+### Ready-to-use images
+
+The easiest way to use `testcontainers` is to depend on ready-to-use images (aka modules).
+
+Modules are available as a community-maintained crate: [testcontainers-modules](https://github.com/testcontainers/testcontainers-rs-modules-community)
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0
+  ([LICENSE-APACHE](LICENSE-Apache-2.0) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license
+  ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.

testcontainers/src/core/containers/async_container.rs

@@ -19,7 +19,7 @@ use crate::{
 /// go out of scope. However, async drop is not available in rust yet. This implementation
 /// is using block_on.
 ///
-/// ```rust
+/// ```rust,no_run
 /// use testcontainers::*;
 /// #[tokio::test]
 /// async fn a_test() {

testcontainers/src/runners/async_runner.rs

@@ -21,7 +21,7 @@ use crate::{
 ///
 /// ## Example
 ///
-/// ```rust
+/// ```rust,no_run
 /// use testcontainers::{core::WaitFor, runners::AsyncRunner, GenericImage};
 ///
 /// async fn test_redis() {

testcontainers/src/runners/sync_runner.rs

@@ -4,7 +4,7 @@ use crate::{Container, Image, RunnableImage};
 ///
 /// ## Example
 ///
-/// ```rust
+/// ```rust,no_run
 /// use testcontainers::{core::WaitFor, runners::SyncRunner, GenericImage};
 ///
 /// fn test_redis() {