docs: generating module docs, fixing build settings, and working on the standard docs pages for python

Author: terry-docker

Makefile

@@ -78,8 +78,12 @@ DOCS_DOCKERFILE := Dockerfile.docs
 .PHONY: clean-docs
 clean-docs:
 	@echo "Destroying docs"
-	docker rm -f $(DOCS_CONTAINER) || true
-	docker rmi $(DOCS_IMAGE) || true
+	@if docker ps -a --format '{{.Names}}' | grep -q '^$(DOCS_CONTAINER)$$'; then \
+		docker rm -f $(DOCS_CONTAINER); \
+	fi
+	@if docker images -q $(DOCS_IMAGE) | grep -q .; then \
+		docker rmi $(DOCS_IMAGE); \
+	fi
 
 .PHONY: docs-ensure-image
 docs-ensure-image:
@@ -96,15 +100,6 @@ serve-docs: docs-ensure-image
 			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:

docs/contributing.md

@@ -1,71 +1,96 @@
-# Contributing
+# Contributing to `testcontainers-python`
 
-`Testcontainers for Go` is open source, and we love to receive contributions from our community — you!
+Welcome to the `testcontainers-python` community!
+This should give you an idea about how we build, test and release `testcontainers-python`!
 
-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.
+Highly recommended to read this document thoroughly to understand what we're working on right now
+and what our priorities are before you are trying to contribute something.
 
-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.
+This will greatly increase your chances of getting prompt replies as the maintainers are volunteers themselves.
 
-## Questions
+## Before you begin
 
-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.
+We recommend following these steps:
 
-## Code contributions
+1. Finish reading this document.
+2. Read the [recently updated issues](https://github.com/testcontainers/testcontainers-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc){:target="\_blank"}
+3. Look for existing issues on the subject you are interested in - we do our best to label everything correctly
 
-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.
+## Local development
 
-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.
+### Pre-Requisites
 
-### Submitting your changes
+You need to have the following tools available to you:
 
-Please just be sure to:
+- `make` - You'll need a GNU Make for common developer activities
+- `poetry` - This is the primary package manager for the project
+- `pyenv` **Recommended**: For installing python versions for your system.
+  Poetry infers the current latest version from what it can find on the `PATH` so you are still fine if you don't use `pyenv`.
 
-- 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.
+### Build and test
 
-!!!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).
+- Run `make install` to get `poetry` to install all dependencies and set up `pre-commit`
+  - **Recommended**: Run `make` or `make help` to see other commands available to you.
+- After this, you should have a working virtual environment and proceed with writing code with your favorite IDE
+- **TIP**: You can run `make core/tests` or `make modules/<my-module>/tests` to run the tests specifically for that to speed up feedback cycles
+- You can also run `make lint` to run the `pre-commit` for the entire codebase.
 
-- 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
+## Adding new modules
 
-  > === 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
+We have an [issue template](https://github.com/testcontainers/testcontainers-python/blob/main/.github/ISSUE_TEMPLATE/new-container.md){:target="\_blank"} for adding new module containers, please refer to that for more information.
+Once you've talked to the maintainers (we do our best to reply!) then you can proceed with contributing the new container.
 
-- when updating the `go.mod` file, please run `make tidy-all` to ensure all modules are updated.
+!!!WARNING
+
+    Please raise an issue before you try to contribute a new container! It helps maintainersunderstand your use-case and motivation.
+    This way we can keep pull requests forced on the "how", not the "why"! :pray:
+    It also gives maintainers a chance to give you last-minute guidance on caveats orexpectations, particularly with
+    new extra dependencies and how to manage them.
+
+### Module documentation
+
+Leave examples for others with your mew module such as `modules/<new_module>/basic_example.py`. You can create as many examples as you want.
+
+Create a new `docs/modules/<new_module>.md` describing the basic use of the new container. There is a [starter template provided here](https://raw.githubusercontent.com/testcontainers/testcontainers-python/blob/main/docs/modules/template.md){:target="\_blank"}.
+
+!!! important
+
+    Make sure to add your new module to the sidebar nav in the `mkdocs.yml`
+
+## Raising issues
+
+We have [Issue Templates](https://raw.githubusercontent.com/testcontainers/testcontainers-python/refs/heads/main/.github/ISSUE_TEMPLATE/new-container.md){:target="\_blank"} to cover most cases, please try to adhere to them, they will guide you through the process.
+Try to look through the existing issues before you raise a new one.
+
+## Releasing versions
+
+We have automated Semantic Versioning and release via [release-please](https://github.com/testcontainers/testcontainers-python/blob/main/.github/workflows/release-please.yml){:target="\_blank"}.
+This takes care of:
+
+- Detecting the next version, based on the commits that landed on `main`
+- When a Release PR has been merged
+  - Create a GitHub Release with the CHANGELOG included
+  - Update the [CHANGELOG](https://github.com/testcontainers/testcontainers-python/blob/main/CHANGELOG.md){:target="\_blank"}, similar to the GitHub Release
+  - Release to PyPI via a [trusted publisher](https://docs.pypi.org/trusted-publishers/using-a-publisher/){:target="\_blank"}
+  - Automatically script updates in files where it's needed instead of hand-crafting it (i.e. in `pyproject.toml`)
+
+!!!DANGER
+
+    Community modules are supported on a best-effort basis and for maintenance reasons, any change to them
+    is only covered under minor and patch changes.
+    Community modules changes DO NOT contribute to major version changes!
+    If your community module container was broken by a minor or patch version change, check out the change logs!
 
 ## 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.
+The _Testcontainers for Go_ documentation is a static site built with [MkDocs](https://www.mkdocs.org/){:target="\_blank"}.
+We use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/){:target="\_blank"} 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:
+To include code snippets in the documentation, we use the [codeinclude plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin){:target="\_blank"}, 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/>
 
@@ -75,7 +100,7 @@ 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.
+Please refer to the [codeinclude plugin documentation](https://github.com/rnorth/mkdocs-codeinclude-plugin){:target="\_blank"} for more information.
 
 ### Previewing rendered content
 
@@ -93,7 +118,7 @@ Once finished, you can destroy the container with the following command:
 make clean-docs
 ```
 
-### PR Preview deployments
+### 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.

docs/contributing_docs.md

@@ -126,3 +126,11 @@ body .card-grid-item:focus {
         height: 1.75em;
     }
 }
+
+.md-typeset__table {
+    min-width: 100%;
+ }
+
+ .md-typeset table:not([class]) {
+    display: table;
+}

docs/css/extra.css

@@ -0,0 +1,29 @@
+# Custom configuration
+
+.....
+
+## Docker host detection
+
+_Testcontainers for Go_ will attempt to detect the Docker environment and configure everything to work automatically.
+
+However, sometimes customization is required. _Testcontainers for Go_ will respect the following order:
+
+1. Read the **tc.host** property in the `~/.testcontainers.properties` file. E.g. `tc.host=tcp://my.docker.host:1234`
+
+2. Read the **DOCKER_HOST** environment variable. E.g. `DOCKER_HOST=unix:///var/run/docker.sock`
+   See [Docker environment variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) for more information.
+
+3. Read the Go context for the **DOCKER_HOST** key. E.g. `ctx.Value("DOCKER_HOST")`. This is used internally for the library to pass the Docker host to the resource reaper.
+
+4. Read the default Docker socket path, without the unix schema. E.g. `/var/run/docker.sock`
+
+5. Read the **docker.host** property in the `~/.testcontainers.properties` file. E.g. `docker.host=tcp://my.docker.host:1234`
+
+6. Read the rootless Docker socket path, checking in the following alternative locations:
+
+   1. `${XDG_RUNTIME_DIR}/.docker/run/docker.sock`.
+   2. `${HOME}/.docker/run/docker.sock`.
+   3. `${HOME}/.docker/desktop/docker.sock`.
+   4. `/run/user/${UID}/docker.sock`, where `${UID}` is the user ID of the current user.
+
+7. The library panics if none of the above are set, meaning that the Docker host was not detected.