feat: scaffolding out a new docs site

Author: terry-docker

.gitignore

@@ -72,3 +72,6 @@ venv
 .python-version
 .env
 .github-token
+
+# docs build
+site/

Dockerfile.docs

@@ -0,0 +1,5 @@
+FROM python:3.11-slim
+
+RUN pip install poetry
+
+WORKDIR /docs

Makefile

@@ -68,3 +68,44 @@ clean-all: clean ## Remove all generated files and reset the local virtual envir
 .PHONY: help
 help:  ## Display command usage
 	@grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+## --------------------------------------
+
+DOCS_CONTAINER=mkdocs-container
+DOCS_IMAGE=mkdocs-poetry
+DOCS_DOCKERFILE := Dockerfile.docs
+
+.PHONY: clean-docs
+clean-docs:
+	@echo "Destroying docs"
+	docker rm -f $(DOCS_CONTAINER) || true
+	docker rmi $(DOCS_IMAGE) || true
+
+.PHONY: docs-ensure-image
+docs-ensure-image:
+	@if [ -z "$$(docker images -q $(DOCS_IMAGE))" ]; then \
+		docker build -f $(DOCS_DOCKERFILE) -t $(DOCS_IMAGE) . ; \
+	fi
+
+.PHONY: serve-docs
+serve-docs: docs-ensure-image
+	docker run --rm --name $(DOCS_CONTAINER) -it -p 8000:8000 \
+		-v $(PWD):/testcontainers-go \
+		-w /testcontainers-go \
+		$(DOCS_IMAGE) bash -c "\
+			cd docs && poetry install --no-root && \
+			poetry run mkdocs serve -f ../mkdocs.yml -a 0.0.0.0:8000"
+
+.PHONY: watch-docs
+watch-docs: docs-ensure-image
+	docker run --rm --name $(DOCS_CONTAINER) -it -p 8000:8000 \
+		-v $(PWD):/testcontainers-go \
+		-w /testcontainers-go \
+		$(DOCS_IMAGE) bash -c "\
+			cd docs && poetry install --no-root && \
+			poetry run mkdocs serve -f ../mkdocs.yml -a 0.0.0.0:8000" --live-reload
+
+# Needed if dependencies are added to the docs site
+.PHONY: export-docs-deps
+export-docs-deps:
+	cd docs && poetry export --without-hashes --output requirements.txt

docs/_headers

@@ -0,0 +1,2 @@
+/search/search_index.json
+  Access-Control-Allow-Origin: *

docs/_redirects

@@ -0,0 +1,101 @@
+# Contributing
+
+`Testcontainers for Go` is open source, and we love to receive contributions from our community — you!
+
+There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests, or writing code for the core library or for a technology module.
+
+In any case, if you like the project, please star the project on [GitHub](https://github.com/testcontainers/testcontainers-go/stargazers) and help spread the word :)
+Also join our [Slack workspace](http://slack.testcontainers.org) to get help, share your ideas, and chat with the community.
+
+## Questions
+
+GitHub is reserved for bug reports and feature requests; it is not the place for general questions.
+If you have a question or an unconfirmed bug, please visit our [Slack workspace](https://testcontainers.slack.com/);
+feedback and ideas are always welcome.
+
+## Code contributions
+
+If you have a bug fix or new feature that you would like to contribute, please find or open an [issue](https://github.com/testcontainers/testcontainers-go/issues) first.
+It's important to talk about what you would like to do, as there may already be someone working on it,
+or there may be context to be aware of before implementing the change.
+
+Next would be to fork the repository and make your changes in a feature branch. **Please do not commit changes to the `main` branch**,
+otherwise we won't be able to contribute to your changes directly in the PR.
+
+### Submitting your changes
+
+Please just be sure to:
+
+- follow the style, naming and structure conventions of the rest of the project.
+- make commits atomic and easy to merge.
+- use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for the PR title. This will help us to understand the nature of the changes, and to generate the changelog after all the commits in the PR are squashed.
+  - Please use the `feat!`, `chore!`, `fix!`... types for breaking changes, as these categories are considered as `breaking change` in the changelog. Please use the `!` to denote a breaking change.
+  - Please use the `security` type for security fixes, as these categories are considered as `security` in the changelog.
+  - Please use the `feat` type for new features, as these categories are considered as `feature` in the changelog.
+  - Please use the `fix` type for bug fixes, as these categories are considered as `bug` in the changelog.
+  - Please use the `docs` type for documentation updates, as these categories are considered as `documentation` in the changelog.
+  - Please use the `chore` type for housekeeping commits, including `build`, `ci`, `style`, `refactor`, `test`, `perf` and so on, as these categories are considered as `chore` in the changelog.
+  - Please use the `deps` type for dependency updates, as these categories are considered as `dependencies` in the changelog.
+
+!!!important
+There is a GitHub Actions workflow that will check if your PR title follows the conventional commits convention. If not, it contributes a failed check to your PR.
+To know more about the conventions, please refer to the [workflow file](https://github.com/testcontainers/testcontainers-go/blob/main/.github/workflows/conventions.yml).
+
+- use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for your commit messages, as it improves the readability of the commit history, and the review process. Please follow the above conventions for the PR title.
+- unless necessary, please try to **avoid pushing --force** to the published branch you submitted a PR from, as it makes it harder to review the changes from a given previous state.
+- apply format running `make lint-all`. It will run `golangci-lint` for the core and modules with the configuration set in the root directory of the project. Please be aware that the lint stage on CI could fail if this is not done.
+  - For linting just the modules: `make -C modules lint-modules`
+  - For linting just the examples: `make -C examples lint-examples`
+  - For linting just the modulegen: `make -C modulegen lint`
+- verify all tests are passing. Build and test the project with `make test-all` to do this.
+  _ For a given module or example, go to the module or example directory and run `make test`.
+  _ If you find an `ld warning` message on MacOS, you can ignore it. It is indeed a warning: https://github.com/golang/go/issues/61229
+
+  > === Errors
+  > ld: warning: '/private/var/folders/3y/8hbf585d4yl6f8j5yzqx6wz80000gn/T/go-link-2319589277/000018.o' has malformed LC_DYSYMTAB, expected 98 undefined symbols to start at index 1626, found 95 undefined symbols starting at index 1626
+
+- when updating the `go.mod` file, please run `make tidy-all` to ensure all modules are updated.
+
+## Documentation contributions
+
+The _Testcontainers for Go_ documentation is a static site built with [MkDocs](https://www.mkdocs.org/).
+We use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, which offers a number of useful extensions to MkDocs.
+
+We publish our documentation using Netlify.
+
+### Adding code snippets
+
+To include code snippets in the documentation, we use the [codeinclude plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin), which uses the following syntax:
+
+> &lt;!--codeinclude--&gt;<br/> > &#91;Human readable title for snippet&#93;(./relative_path_to_example_code.go) targeting_expression<br/> > &#91;Human readable title for snippet&#93;(./relative_path_to_example_code.go) targeting_expression<br/> > &lt;!--/codeinclude--&gt;<br/>
+
+Where each title snippet in the same `codeinclude` block would represent a new tab
+in the snippet, and each `targeting_expression` would be:
+
+- `block:someString` or
+- `inside_block:someString`
+
+Please refer to the [codeinclude plugin documentation](https://github.com/rnorth/mkdocs-codeinclude-plugin) for more information.
+
+### Previewing rendered content
+
+From the root directory of the repository, you can use the following command to build and serve the documentation locally:
+
+```shell
+make serve-docs
+```
+
+It will use a Docker container to install the required dependencies and start a local server at `http://localhost:8000`.
+
+Once finished, you can destroy the container with the following command:
+
+```shell
+make clean-docs
+```
+
+### PR Preview deployments
+
+Note that documentation for pull requests will automatically be published by Netlify as 'deploy previews'.
+These deployment previews can be accessed via the `deploy/netlify` check that appears for each pull request.
+
+Please check the GitHub comment Netlify posts on the PR for the URL to the deployment preview.

docs/contributing.md

@@ -0,0 +1,109 @@
+# Contributing to documentation
+
+The Testcontainers for Java documentation is a static site built with [MkDocs](https://www.mkdocs.org/).
+We use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, which offers a number of useful extensions to MkDocs.
+
+In addition we use a [custom plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin) for inclusion of code snippets.
+
+We publish our documentation using Netlify.
+
+## Previewing rendered content
+
+### Using Docker locally
+
+The root of the project contains a `docker-compose.yml` file. Simply run `docker-compose up` and then access the docs at [http://localhost:8000](http://localhost:8000).
+
+### Using Python locally
+
+* Ensure that you have Python 3.8.0 or higher.
+* Set up a virtualenv and run `pip install -r requirements.txt` in the `testcontainers-java` root directory.
+* Once Python dependencies have been installed, run `mkdocs serve` to start a local auto-updating MkDocs server.
+
+### PR Preview deployments
+
+Note that documentation for pull requests will automatically be published by Netlify as 'deploy previews'.
+These deployment previews can be accessed via the `deploy/netlify` check that appears for each pull request.
+
+## Codeincludes
+
+The Gradle project under `docs/examples` is intended to hold compilable, runnable example code that can be included as
+snippets into the documentation at build-time.
+
+As a result, we can have more confidence that code samples shown in the documentation is valid.
+
+We use a custom plugin for MkDocs to include snippets into our docs.
+
+A codeinclude block will resemble a regular markdown link surrounded by a pair of XML comments, e.g.:
+
+<!--
+To prevent this from being rendered as a codeinclude when rendering this page, we use HTML tags.
+See this in its rendered form to understand its actual appearance, or look at other pages in the
+docs.
+-->
+
+<pre><code>&lt;!--codeinclude--&gt;
+[Human readable title for snippet](./relative_path_to_example_code.java) targeting_expression
+&lt;!--/codeinclude--&gt;
+</code></pre>
+
+Where `targeting_expression` could be:
+
+* `block:someString` or
+* `inside_block:someString`
+
+If these are provided, the macro will seek out any line containing the token `someString` and grab the next curly brace
+delimited block that it finds. `block` will grab the starting line and closing brace, whereas `inside_block` will omit
+these.
+
+e.g., given:
+```java
+
+public class FooService {
+
+    public void doFoo() {
+        foo.doSomething();
+    }
+
+    ...
+
+```
+
+If we use `block:doFoo` as our targeting expression, we will have the following content included into our page:
+
+```java
+public void doFoo() {
+    foo.doSomething();
+}
+```
+
+Whereas using `inside_block:doFoo` we would just have the inner content of the method included:
+
+```java
+foo.doSomething();
+```
+
+Note that:
+
+* Any code included will have its indentation reduced
+* Every line in the source file will be searched for an instance of the token (e.g. `doFoo`). If more than one line
+  includes that token, then potentially more than one block could be targeted for inclusion. It is advisable to use a
+  specific, unique token to avoid unexpected behaviour.
+
+When we wish to include a section of code that does not naturally appear within braces, we can simply insert our token,
+with matching braces, in a comment.
+While a little ugly, this has the benefit of working in any context and is easy to understand.
+For example:
+
+```java
+public class FooService {
+
+    public void boringMethod() {
+        doSomethingBoring();
+
+        // doFoo {
+        doTheThingThatWeActuallyWantToShow();
+        // }
+    }
+
+
+```