docs: improve experience for creating modules for first time (testcon…

…tainers#1690)

* docs: improve experience for creating modules for first time

* fix: use parent dir in examples template

* fix: do not generate examples for the example module

We can revisit the need for examples in the short term, as the
testable examples seems the way to go from now on

docs/modules/index.md

@@ -47,14 +47,15 @@ We have provided a command line tool to generate the scaffolding for the code of
 From the [`modulegen` directory]({{repo_url}}/tree/main/modulegen), please run:
 
 ```shell
-go run . new example --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
+go run . new module --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
 ```
 
-or for creating a Go module:
+!!!info
+    In the case you just want to create [an example module](../examples/index.md), with no public API, please run:
 
-```shell
-go run . new module --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
-```
+    ```shell
+    go run . new example --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
+    ```
 
 ### Adding types and methods to the module
 

modulegen/_template/examples_test.go.tmpl

@@ -5,7 +5,7 @@ import (
 	"fmt"
 
 	"github.com/testcontainers/testcontainers-go"
-	"github.com/testcontainers/testcontainers-go/modules/{{ $lower }}"
+	"github.com/testcontainers/testcontainers-go/{{ ParentDir }}/{{ $lower }}"
 )
 
 func Example{{ $entrypoint }}() {

modulegen/internal/module/main.go

@@ -53,7 +53,14 @@ func generateGoModFile(moduleDir string, tcModule context.TestcontainersModule)
 }
 
 func GenerateFiles(moduleDir string, moduleName string, funcMap template.FuncMap, tcModule any) error {
-	for _, tmpl := range []string{"examples_test.go", "module_test.go", "module.go"} {
+	templates := []string{"module_test.go", "module.go"}
+
+	tcModuleCtx := tcModule.(context.TestcontainersModule)
+	if tcModuleCtx.IsModule {
+		templates = append(templates, "examples_test.go")
+	}
+
+	for _, tmpl := range templates {
 		name := tmpl + ".tmpl"
 		t, err := template.New(name).Funcs(funcMap).ParseFiles(filepath.Join("_template", name))
 		if err != nil {

modulegen/main_test.go

@@ -292,7 +292,7 @@ func TestGenerate(t *testing.T) {
 	assertModuleGithubWorkflowContent(t, module, mainWorkflowFile)
 
 	generatedTemplatesDir := filepath.Join(examplesTmp, moduleNameLower)
-	assertExamplesTestContent(t, module, filepath.Join(generatedTemplatesDir, "examples_test.go"))
+	// do not generate examples_test.go for examples
 	assertModuleTestContent(t, module, filepath.Join(generatedTemplatesDir, moduleNameLower+"_test.go"))
 	assertModuleContent(t, module, filepath.Join(generatedTemplatesDir, moduleNameLower+".go"))
 	assertGoModContent(t, module, originalConfig.Extra.LatestVersion, filepath.Join(generatedTemplatesDir, "go.mod"))