docs: use Go testable examples in modules

docs/features/creating_networks.md

@@ -0,0 +1,13 @@
+# How to create a network
+
+Apart from creating containers, `Testcontainers for Go` also allows you to create networks. This is useful when you need to connect multiple containers to the same network.
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a network](../../network_test.go) inside_block:createNetwork
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Creating a network with IPAM](../../network_test.go) inside_block:withIPAM
+<!--/codeinclude-->

docs/modules/artemis.md

@@ -17,7 +17,11 @@ go get github.com/testcontainers/testcontainers-go/modules/artemis
 ## Usage example
 
 <!--codeinclude-->
-[Creating and connecting to an Artemis container](../../modules/artemis/example_test.go) inside_block:ExampleRunContainer
+[Creating to an Artemis container](../../modules/artemis/examples_test.go) inside_block:runArtemisContainer
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Connecting to an Artemis container](../../modules/artemis/examples_test.go) inside_block:connectToArtemisContainer
 <!--/codeinclude-->
 
 ## Module reference
@@ -58,7 +62,7 @@ If you need to change the default admin credentials (i.e. `artemis:artemis`) use
 [With credentials](../../modules/artemis/artemis_test.go) inside_block:withCredentials
 <!--/codeinclude-->
 
-#### Anonymous Login
+#### Enable Anonymous login
 
 If you need to enable anonymous logins (which are disabled by default) use `WithAnonymousLogin`.
 
@@ -71,7 +75,9 @@ If you need to enable anonymous logins (which are disabled by default) use `With
 If you need to pass custom arguments to the `artemis create` command, use `WithExtraArgs`.
 The default is `--http-host 0.0.0.0 --relax-jolokia`.
 Setting this value will override the default.
-See the documentation on `artemis create` for available options.
+
+!!!info
+    Please see the documentation on `artemis create` for the available options here: [https://activemq.apache.org/components/artemis/documentation/latest/using-server.html#options](https://activemq.apache.org/components/artemis/documentation/latest/using-server.html#options)
 
 <!--codeinclude-->
 [With Extra Arguments](../../modules/artemis/artemis_test.go) inside_block:withExtraArgs
@@ -96,15 +102,15 @@ The Artemis container exposes the following methods:
 User returns the administrator username.
 
 <!--codeinclude-->
-[Retrieving the Administrator User](../../modules/artemis/example_test.go) inside_block:containerUser
+[Retrieving the Administrator User](../../modules/artemis/examples_test.go) inside_block:containerUser
 <!--/codeinclude-->
 
 #### Password
 
 Password returns the administrator password.
 
 <!--codeinclude-->
-[Retrieving the Administrator Password](../../modules/artemis/example_test.go) inside_block:containerPassword
+[Retrieving the Administrator Password](../../modules/artemis/examples_test.go) inside_block:containerPassword
 <!--/codeinclude-->
 
 #### BrokerEndpoint

docs/modules/clickhouse.md

@@ -17,9 +17,7 @@ go get github.com/testcontainers/testcontainers-go/modules/clickhouse
 ## Usage example
 
 <!--codeinclude-->
-
-[Test for a ClickHouse container](../../modules/clickhouse/clickhouse_test.go)inside_block:customInitialization
-
+[Test for a ClickHouse container](../../modules/clickhouse/examples_test.go) inside_block:runClickHouseContainer
 <!--/codeinclude-->
 
 ## Module reference
@@ -33,6 +31,14 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 - `context.Context`, the Go context.
 - `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
 
+### Container Ports
+
+Here you can find the list with the default ports used by the ClickHouse container.
+
+<!--codeinclude-->
+[Container Ports](../../modules/clickhouse/clickhouse.go) inside_block:containerPorts
+<!--/codeinclude-->
+
 ### Container Options
 
 When starting the ClickHouse container, you can pass options in a variadic way to configure it.
@@ -65,13 +71,7 @@ Please read the [Create containers: Advanced Settings](../features/creating_cont
 #### Set username, password and database name
 
 If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
-options.
-
-<!--codeinclude-->
-
-[Custom Database initialization](../../modules/clickhouse/clickhouse_test.go) inside_block:customInitialization
-
-<!--/codeinclude-->
+options. E.g. `WithUsername("user")`, `WithPassword("password")`, `WithDatabase("db")`.
 
 !!!info
     The default values for the username is `default`, for password is `clickhouse` and for the default database name is `clickhouse`.
@@ -84,42 +84,46 @@ it will run any `*.sql` files, run any executable `*.sh` scripts, and source any
 initialization before starting the service.
 
 <!--codeinclude-->
-
 [Include init scripts](../../modules/clickhouse/clickhouse_test.go) inside_block:withInitScripts
+<!--/codeinclude-->
 
+<!--codeinclude-->
+[Init script content](../../modules/clickhouse/testdata/init-db.sh)
 <!--/codeinclude-->
 
+#### Custom configuration
+
+If you need to set a custom configuration, the module provides the `WithConfigFile` option to pass the path to a custom configuration file in XML format.
+
 <!--codeinclude-->
+[XML config file](../../modules/clickhouse/testdata/config.xml)
+<!--/codeinclude-->
 
-[Init script content](../../modules/clickhouse/testdata/init-db.sh)
+In the case you want to pass a YAML configuration file, you can use the `WithYamlConfigFile` option.
 
+<!--codeinclude-->
+[YAML config file](../../modules/clickhouse/testdata/config.yaml)
 <!--/codeinclude-->
 
 ### Container Methods
 
 The ClickHouse container exposes the following methods:
 
-#### ConnectionString
-
-This method returns the dsn connection string to connect to the ClickHouse container, using the default configs.
-It's possible to pass extra parameters to the connection string, e.g. `dial_timeout=300ms` or `skip_verify=false`, in a variadic way.
+#### ConnectionHost
 
-e.g. `clickhouse://default:pass@localhost:9000?dial_timeout=300ms&skip_verify=false`
+This method returns the host and port of the ClickHouse container, using the default, native `9000/tcp` port. E.g. `localhost:9000`
 
 <!--codeinclude-->
-
-[Get connection string](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionString
-
+[Get connection host](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionHost
 <!--/codeinclude-->
 
-#### ConnectionHost
+#### ConnectionString
 
-This method returns the host & port of the ClickHouse container.
+This method returns the dsn connection string to connect to the ClickHouse container, using the default, native `9000/tcp` port obtained from the `ConnectionHost` method.
+It's possible to pass extra parameters to the connection string, e.g. `dial_timeout=300ms` or `skip_verify=false`, in a variadic way.
 
-e.g. `localhost:9000`
+e.g. `clickhouse://default:pass@localhost:9000?dial_timeout=300ms&skip_verify=false`
 
 <!--codeinclude-->
-
-[Get connection host](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionHost
-
+[Get connection string](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionString
 <!--/codeinclude-->

docs/modules/couchbase.md

@@ -17,7 +17,7 @@ go get github.com/testcontainers/testcontainers-go/modules/couchbase
 ## Usage example
 
 <!--codeinclude-->
-[Start Couchbase](../../modules/couchbase/couchbase_test.go) inside_block:withBucket
+[Creating a Couchbase container](../../modules/couchbase/examples_test.go) inside_block:runCouchbaseContainer
 <!--/codeinclude-->
 
 ## Module Reference
@@ -49,6 +49,11 @@ Once the container is started, it will perform the following operations, **in th
 
 ### Container Ports
 
+Here you can find the list with the default ports used by the Couchbase container. The Management ports (`MGMT_PORT` and `MGMT_SSL_PORT`) and the Service ports for `kv`, `query` and `search` are exposed by default.
+
+!!!tip
+	You can export the service ports for Analytics and Eventing by using the `WithServiceAnalytics` and `WithServiceEventing` optional functions.
+
 <!--codeinclude-->
 [Container Ports](../../modules/couchbase/couchbase.go) inside_block:containerPorts
 <!--/codeinclude-->
@@ -68,6 +73,12 @@ By default, the container will use the following Docker image:
 [Default Docker image](../../modules/couchbase/couchbase.go) inside_block:defaultImage
 <!--/codeinclude-->
 
+You can find the Docker images that are currently tested in this module, for the Enterprise and Community editions, in the following list:
+
+<!--codeinclude-->
+[Docker images](../../modules/couchbase/couchbase_test.go) inside_block:dockerImages
+<!--/codeinclude-->
+
 #### Wait Strategies
 
 If you need to set a different wait strategy for Couchbase, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
@@ -94,12 +105,12 @@ If you need to change the default credentials for the admin user, you can use `W
 When the password has less than 6 characters, the container won't be created and the `RunContainer` function will throw an error.
 
 !!!info
-	The default username is `Administrator` and the default password is `password`.
+	In the case this optional function is not called, the default username is `Administrator` and the default password is `password`.
 
 #### Buckets
 
-When creating a new Couchbase container, you can create one or more buckets. The module provides with a `WithBuckets` function that accepts an array of buckets to be created.
-To create a new bucket, the module exposes a `NewBucket` function, where you can pass the bucket name.
+When creating a new Couchbase container, you can create one or more buckets. The module exposes a `WithBuckets` optional function that accepts an slice of buckets to be created.
+To create a new bucket, the module also exposes a `NewBucket` function, where you can pass the bucket name.
 
 It's possible to customize a newly created bucket, using the following options:
 
@@ -131,33 +142,17 @@ By default, the container will start with the following services: `kv`, `n1ql`,
 	When running the Enterprise Edition of Couchbase Server, the module provides two functions to enable or disable services:
 	`WithServiceAnalytics` and `WithServiceEventing`. Else, it will throw an error and the container won't be created.
 
-<!--codeinclude-->
-[Docker images](../../modules/couchbase/couchbase_test.go) inside_block:dockerImages
-<!--/codeinclude-->
-
 ### Container Methods
 
 #### ConnectionString
 
 The `ConnectionString` method returns the connection string to connect to the Couchbase container instance. 
 It returns a string with the format `couchbase://<host>:<port>`.
 
-<!--codeinclude-->
-[Connect to Couchbase](../../modules/couchbase/couchbase_test.go) inside_block:connectToCluster
-<!--/codeinclude-->
-
 #### Username
 
 The `Username` method returns the username of the Couchbase administrator. 
 
-<!--codeinclude-->
-[Connect to Couchbase using Credentials](../../modules/couchbase/couchbase_test.go) inside_block:getCredentials
-<!--/codeinclude-->
-
 #### Password
 
 The `Password` method returns the password of the Couchbase administrator.
-
-<!--codeinclude-->
-[Connect to Couchbase using Credentials](../../modules/couchbase/couchbase_test.go) inside_block:getCredentials
-<!--/codeinclude-->

docs/modules/index.md

@@ -11,12 +11,14 @@ We have provided a command line tool to generate the scaffolding for the code of
     - a Go package named after the module, in lowercase
     - a Go file for the creation of the container, using a dedicated struct in which the image flag is set as Docker image.
     - a Go test file for running a simple test for your container, consuming the above struct.
+    - a Go examples file for running the example in the docs site, also adding them to [https://pkg.go.dev](https://pkg.go.dev).
     - a Makefile to run the tests in a consistent manner
 - a markdown file in the docs/modules directory including the snippets for both the creation of the container and a simple test. By default, this generated file will contain all the documentation for the module, including:
     - the version of _Testcontainers for Go_ in which the module was added.
     - a short introduction to the module.
     - a section for adding the module to the project dependencies.
-    - a section for a usage example.
+    - a section for a usage example, including:
+        - a snippet for creating the container, from the `examples_test.go` file in the Go module.
     - a section for the module reference, including:
         - the entrypoint function for creating the container.
         - the options for creating the container.

docs/modules/k3s.md

@@ -17,7 +17,7 @@ go get github.com/testcontainers/testcontainers-go/modules/k3s
 ## Usage example
 
 <!--codeinclude-->
-[Test for a K3s container](../../modules/k3s/k3s_test.go) inside_block: k3sRunContainer
+[Test for a K3s container](../../modules/k3s/k3s_test.go) inside_block:runK3sContainer
 <!--/codeinclude-->
 
 ## Module reference