feat: provide a tool to generate examples from code

[mdelapenya]

What does this PR do?

It moves the existing examples' code (cockroachDB, nginx, pulsar and redis) to separate example Go modules that will be automatically included into the docs site.

Besides, we have provided a command line tool to generate the scaffolding for the code of a new example. This tool will generate:

• a Go module for the example, including:
  • go.mod and go.sum files
  • a Go package named after the example, in lowercase
  • a Go file for the creation of the container, using a dedicated struct.
  • a Go test file for running a simple test for your container, consuming the above struct.
  • a Makefile to run the tests in a consistent manner
  • a tools.go file including the build tools (i.e. gotestsum) used to build/run the example.
• a GH action workflow for the example, which runs the tests for the example to ensure compilation and green tests. It runs for pushes and pull-request events.
• a markdown file in the docs/examples directory including the snippets for both the creation of the container and a simple test.

This tool is not doing the following:

• If the example already exists, it will exit without updating the existing files.
• You have to manually add the markdown entry in the docs to the mkdocs.yml file in the root directory of the project. It will generate the navigation menu for the docs website. Implemented in this PR 🚀

In this PR we are adding a Make goal to run all the examples' tests, in order to check if they are still valid and not outdated. The make goal, which calls each example's Makefile, is used in the CI pipeline for each example.

Why is it important?

Examples embedded into the docs could get outdated and they could not even compile. With this approach, the tests will be part of the test suite.

We expect the code generation tool will simplify how to start an example, creating the scaffolding for it.

Related issues

• Supersedes feat: provide a tool to generate examples from code #603

Follow-up questions

• Do we want to run the tests for the examples for the two supported versions of Go (current and current-1)?
• Do we want to run the tests for the examples in separated pipelines? I think so
• What's the frequency in which we want to run the tests for the examples? Pull Requests, pushes, tags...
• Do we want to add the examples GH checks to the branch protection settings to make them mandatory?

[mdelapenya]

I'm tempted to have a dedicated pipeline for each example, instead of adding build time to the main one. Wdyt? If that's the case, should the checks be mandatory for the review?

[mdelapenya]

@eddumelendez and I had a chat on this PR, and we are going to merge as is, creating follow-up PRs adding more examples.