[Documentation]: The docs don't always prepend the package to types

[Minivera]

Proposal

In the docs, many pages have code example you can copy, but those examples don't always contain the package that contains the structs used in the example as a prefix, this is the case for the Dockerfile docs, parts of the networking docs, and the files and mounts docs, to name a few.

This makes this code not directly usable when a user wants to try things out by first copy/pasting the example, then modifying once they see what happens. It's a minor thing, but testcontainers. needs to be prefixed to every struct every time they copy something, which can lead to errors if they forget to do so.

It'd be great if the docs could include these prefix on all structs, or possibly have the examples in context as a separate tab in the code blocks, so we can see the code used in a real test.

[mdelapenya]

Thanks for opening this issue, but I'm afraid it will not be as easy: the docs site is able to embed files from the source code, and we do have two types of test files where to grab those code snippets:

• testable examples that directly land into pkg.go.dev, This is the preferred place to get the code snippets, as they don't have references to the testing library and assertions
• real tests. They usually have the same package, e.g. testcontainers , instead of testcontainers_test which would enforce the package namespace in the code snippets. In the modules, we enforce that pattern thanks to the module generator tool, but not in the library (yet).

I'd be more than happy with having more hands rewriting all test files with this "_test" pattern 😄 As a direct consequence, all code snippets that are embedded from the test files will automatically receive the update.

[Minivera]

I'm more than open to make that PR if it'd help 🙂 Though, pure curiosity, would it be doable to potentially transform the generated docs HTML/content (not sure how the docs are generated, yet) once it has been generated? Maybe we could look at keeping a reference to all the structs from testcontainers and see if they are missing the prefix, and add it post generation if it's missing it? Just an idea.

[mdelapenya]

We currently use mkdocs as docs system, and we are in the middle of merging all the Testcontainers language's docs to one single place (e.g. from golang.testcontainers.org to testcontainers.com). So I'm sure once there, we could find a better way to auto-generate things as you suggest.

In the mean time, I'd go with the test packages.

[Minivera]

I started a PR with your suggested changes for the test packages, let me know if that's not what you had in mind 😄