Merge pull request #27 from testcontainers/docs-site

Add a project site, roadmap and initial documentation pages

.devcontainer/Dockerfile

@@ -0,0 +1,4 @@
+FROM python:3.10.4-slim-buster
+
+RUN apt-get update
+RUN apt-get install -y libsass-dev build-essential libcairo2 git libpango-1.0-0 libpangoft2-1.0-0 pangocairo-1.0 pngquant

.devcontainer/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2024 Kento Shimada, Oleg Nenashev, and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.devcontainer/README.md

@@ -0,0 +1,8 @@
+# Testcontainers for C/C++. DevContainer
+
+This is an experimental Dev Container for the project site that
+does not yet include the build tools.
+
+## Included Toolchains
+
+- Python/MkDocs - for the project site and documentation development

.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+// Credits - https://github.com/hitsumabushi845/MkDocs-with-Remote-Containers
+{
+    "name": "Material for MkDocs",
+    "dockerFile": "Dockerfile",
+    "customizations": {
+      "vscode": {
+        // Set *default* container specific settings.json values on container create.
+        "settings": {
+          "terminal.integrated.shell.linux": "/bin/bash",
+          "debug.javascript.usePreview": false
+        },
+        // Add the IDs of extensions you want installed when the container is created.
+        "extensions": [
+          "yzhang.markdown-all-in-one",
+          "redhat.vscode-yaml",
+          "shardulm94.trailing-spaces",
+          "oderwat.indent-rainbow",
+          "msjsdiag.debugger-for-chrome"
+        ],
+      },
+    },
+    // Use 'forwardPorts' to make a list of ports inside the container available locally.
+    "forwardPorts": [
+      8000
+    ],
+    // Use 'postCreateCommand' to run commands after the container is created.
+    "postCreateCommand": "pip3 install -r .devcontainer/requirements.txt "
+    // Uncomment to connect as a non-root user. See https://aka.ms/vscode-remote/containers/non-root.
+    //"remoteUser": "vscode"
+  }
+

.devcontainer/requirements.txt

@@ -0,0 +1,33 @@
+Markdown==3.5
+MarkupSafe==2.1.3
+mergedeep==1.3.4
+mkdocs==1.6.0
+mkdocs-autorefs==0.5.0
+mkdocs-macros-plugin==1.0.5
+mkdocs-material==9.5.28
+mkdocs-material[imaging]==9.5.28
+mkdocs-multirepo-plugin==0.6.3
+mkdocs-redirects==1.2.1
+mkdocs-extra-sass-plugin==0.1.0
+mkdocs-render-swagger-plugin==0.1.1
+mkdocs-same-dir==0.1.3
+mkdocs-pdf==0.1.1
+livereload==2.6.3
+lxml==4.9.3
+click==8.1.7
+dacite==1.8.1
+ghp-import==2.1.0
+jinja2==3.1.2
+mypy-extensions==1.0.0
+packaging==23.2
+pathspec==0.11.2
+platformdirs==3.11.0
+python-dateutil==2.8.2
+python-slugify==8.0.1
+pyyaml==6.0.1
+pyyaml-env-tag==0.1
+six==1.16.0
+text-unidecode==1.3
+typing-extensions==4.8.0
+typing-inspect==0.8.0
+watchdog==3.0.0

.github/workflows/ci.yml

@@ -24,3 +24,32 @@ jobs:
           run-build: true
           run-test: true
           test-args: "--output-on-failure"
+
+  build-site:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: "true"
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v2 
+        with:
+            registry: ghcr.io
+            username: ${{ github.repository_owner }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build in the dev container image
+        uses: devcontainers/[email protected]
+        with:
+            imageName: ghcr.io/oleg-nenashev/oleg-nenashev-site-builder
+            cacheFrom: ghcr.io/oleg-nenashev/oleg-nenashev-site-builder
+            push: never
+            runCmd: |
+              mkdocs build

.github/workflows/deploy-site.yml

@@ -0,0 +1,64 @@
+name: Deploy Site to GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build-site:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: "true"
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v2 
+        with:
+            registry: ghcr.io
+            username: ${{ github.repository_owner }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build in the dev container image
+        uses: devcontainers/[email protected]
+        with:
+            imageName: ghcr.io/oleg-nenashev/oleg-nenashev-site-builder
+            cacheFrom: ghcr.io/oleg-nenashev/oleg-nenashev-site-builder
+            push: always
+            runCmd: |
+              mkdocs build
+        
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v1
+
+  deploy-site:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-site
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -25,3 +25,7 @@ testcontainers-c/testcontainers.h
 *.dll
 *.so.0.0.1
 *.dll.0.0.1
+
+## MkDocs
+/.cache
+/_site

CONTRIBUTING.md

@@ -1,14 +1,14 @@
 # Contributing
 
-[![Slack: testcontainers-c on slacktestcontainers.org](https://img.shields.io/badge/Slack-%23testcontainers%E2%80%94c-brightgreen?style=flat&logo=slack)](http://slack.testcontainers.org/)
+[![Slack: testcontainers-c on slack.testcontainers.com](https://img.shields.io/badge/Slack-%23testcontainers%E2%80%94c-brightgreen?style=flat&logo=slack)](https://slack.testcontainers.org/)
 [![Stability: Experimental](https://masterminds.github.io/stability/experimental.svg)](https://masterminds.github.io/stability/experimental.html)
 
 Contributions are welcome!
 For any feedback and suggestions, use GitHub Issues.
 
 ## Community Slack
 
-We use the `#testcontainers-c` channel on [Testcontainers Slack](http://slack.testcontainers.org/).
+We use the `#testcontainers-c` channel on [Testcontainers Slack](https://slack.testcontainers.com/).
 Please join this channel if you want to discuss contributions/strategy/whatever.
 GitHub Issues are recommended for most of the proposals and bug reports though.
 
@@ -35,6 +35,20 @@ To skip the demo builds and tests, use the `SKIP_DEMOS` variable:
 cmake -DSKIP_DEMOS=true .
 ```
 
+## Contributing to the Documentation
+
+The documentation is structured in the MkDocs format and uses Material for MkDocs.
+To develop the site in this repository, start it in the [Dev Containers](.devcontainer/README.md)
+and use the following commands:
+
+```shell
+mkdocs serve
+```
+
+```shell
+mkdocs build
+```
+
 ## Codestyle
 
 ### Public APIs

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Oleg Nenashev, WireMock Inc and all contributors
+Copyright (c) 2023-2024 Oleg Nenashev, WireMock Inc. and all contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -10,12 +10,10 @@
 [![Stability: Experimental](https://masterminds.github.io/stability/experimental.svg)](https://masterminds.github.io/stability/experimental.html)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/oleg-nenashev/testcontainers-c)](https://github.com/oleg-nenashev/testcontainers-c/releases)
 
-> **WARNING**: This is a prototype.
-> There is a lot to do before it can be distributed and used in production,
-> see the GitHub Issues.
-> The plan is to provide vcpkg and Conan packages; now it is an importable CMake project.
-> A feasible level of feature parity with Testcontainers Go is needed too,
-> hence a lot of wrapper coding.
+!!! warning
+    This is a prototype.
+    There is a lot to do before it can be distributed and used in production, see the GitHub Issues
+    and the [project roadmap](./ROADMAP.md)
 
 This is not a standalone [Testcontainers](https://testcontainers.org/) engine,
 but a C-style shared library adapter for native languages like C/C++, D, Lua, Swift, etc.
@@ -34,8 +32,9 @@ Also join the `#testcontainers-c` channel on the [Testcontainers Slack](http://s
 - Minimum HTTP client wrapper to simplify requests and assertions
 - [Testcontainers for Go](https://golang.testcontainers.org/) under the hood
 - Wrappers for native C types to minimize Golang conversion code on the user side
-- Support for C and C++ projects. A fancy C++ wrapper is coming soon
-- Support for Modules, e.g. the [WireMock module](./modules/wiremock/)
+- Support for [C](./docs/c/README.md) and [C++](./docs/cpp/README.md) projects.
+  A fancy C++ wrapper is coming soon
+- Support for [Modules](./modules/README.md)
 
 ## Quick Start
 
@@ -144,97 +143,21 @@ cmake --install ..
 
 ## Documentation
 
-Coming soon: guidelines, specs and code documentation. Check out the examples for now.
+### Using in C/C++/Swift projects
 
-## Usage in C/C++
+- [C projects](./docs/c/README.md)
+- [C++ projects](./docs/cpp/README.md)
+- [Swift projects](./docs/swift/README.md)
 
-- [Using the generic Testcontainer C API](./demo/generic-container/)
-- [Using Testcontainers C in Google Test (C++)](./demo/google-test/)
-- [Using the WireMock module](./demo/wiremock/)
+See [the examples and demos](./demo/README.md) for more examples.
 
-See [the examples and demos](./demo/) for more examples.
-
-## Usage in other languages
+### Using in other languages
 
 TL;DR: You get the C header file, a shared library object or a DLL file from the
-[Testcontainers C](./testcontainers-c/) module,
+[Testcontainers C](./docs/c/README.md) module,
 Then, you know the drill.
 Feel free to contribute examples or SDKs for the languages!
 
-## Modules
-
-As for other Testcontainers implementations, Testcontainers for C/C++ allow writing
-extensions that extend the SDK and APIs to make usage of a particular service provider
-easier.
-The expectation is that the modules are implemented in a separate dynamic library
-and linked to the consumer project.
-
-### Available modules
-
-- Generic container for DYI containers (embedded)
-  - [Demo](./demo/generic-container/)
-- [WireMock](./modules/wiremock/) - for API mocking and integration testing
-  - [Demo](./demo/wiremock/)
-
-### Why modules?
-
-Modules help to simplify test development and maintenance by encapsulating
-domain-specific logic of a target container.
-For example, the WireMock module adds an API to simplify the configuration of the container.
-You can also use modules to create specific asserts for the container,
-or even attach full-fledged API clients for fine-grain testing.
-
-Initializing WireMock with the module:
-
-```c
-#include "testcontainers-c-wiremock.h"
-
-int main() {
-    printf("Creating new container: %s\n", DEFAULT_WIREMOCK_IMAGE);
-    int requestId = tc_wm_new_default_container();
-    tc_wm_with_mapping(requestId, "test_data/hello.json", "hello");
-    struct tc_run_container_return ret = tc_run_container(requestId);
-
-    // ...
-}
-```
-
-The same initialization without a module (using the "Generic Container" API):
-
-<details>
-<summary>
-Show me the Code
-</summary>
-
-```c
-#include "testcontainers-c.h"
-
-#define DEFAULT_IMAGE "wiremock/wiremock:3.1.0-1"
-
-int main() {
-    printf("Using WireMock with the Testcontainers C binding:\n");
-
-    printf("Creating new container: %s\n", DEFAULT_IMAGE);
-    int requestId = tc_new_container_request(DEFAULT_IMAGE);
-    tc_with_exposed_tcp_port(requestId, 8080);
-    tc_with_wait_for_http(requestId, 8080, "/__admin/mappings");
-    tc_with_file(requestId, "test_data/hello.json", "/home/wiremock/mappings/hello.json");
-    struct tc_run_container_return ret = tc_run_container(requestId);
-
-    // ...
-}
-```
-
-</details>
-
-### Creating new modules
-
-You are welcome to contribute more modules in this or a standalone repository!
-
-> **NOTE:** Some modules are stored in this repository for demo and prototyping purposes.
-> If you develop new modules, once `vcpkg` or `Conan` packaging is implemented for Testcontainers C,
-> you might want to develop your module in a standalone repository instead.
-
 ## Credits
 
 Using a complex Golang framework from C/C++ is not trivial.