docs: Update cloud examples with snippets

alhendrickson · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
commit 1af6a7ff90263fd1812c1072876986e66cfce85e
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+
+site/
diff --git a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md
@@ -11,12 +11,29 @@ Deployment through terraform is carried out through two terraform commands, to h
 
 ### Requirements
 - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install)
-- AWS Credentials for an account that can create and destroy resources. 
+- AWS Credentials for an account that can create and destroy resources.
 
+### 1. Get the configuration files
 
-### Steps
+All you need to do is get the few terraform files that have been preconfigured for this example.
 
-### 1. Add Required Secrets for your env
+[Download all Terraform sources for this example](../../../assets/downloads/deployment-examples-aws-kubernetes.zip){ .md-button }
+
+Alternatively you can view the file contents here:
+
+#### eks-cluster terraform files
+
+This terraform configuration will create a new AWS EKS cluster.
+
+{{ embed_all_files_in_directory_as_snippets('aws-kubernetes/eks-cluster') }}
+
+#### kubernetes-deployment terraform files
+
+This terraform configuration will use the helm plugin to run services in kubernetes.
+
+{{ embed_all_files_in_directory_as_snippets('aws-kubernetes/kubernetes-deployment') }}
+
+### 2. Add required secrets for your environment
 This readme uses environment variables for access:
 
 1. See the `.env.example` file for the required details.
@@ -25,7 +42,7 @@ This readme uses environment variables for access:
 
 If desired, see the official documentation for other ways to provide AWS credentials https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration
 
-### 2. Run Terraform
+### 3. Run Terraform
 Terraform is run on two modules for AWS, so we will run one terraform apply in one folder, then another terraform apply in a second folder. 
 
 Initial provisioning takes around 15 minutes.
@@ -48,7 +65,7 @@ terraform init
 terraform apply --auto-approve
 ```
 
-### 3. Accessing the CogStack Platform
+### 4. Accessing the CogStack Platform
 
 Once the deployment is complete and all services are running, you can access the CogStack platform and its components using the following URLs:
 

diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css
@@ -0,0 +1,13 @@
+/*
+ * Long fenced code blocks (including content pulled in via pymdownx.snippets)
+ * stay within a capped height; scroll vertically inside the block.
+ * Tweak --md-code-block-max-height as needed (Material uses CSS variables elsewhere).
+ */
+:root {
+  --md-code-block-max-height: min(70vh, 28rem);
+}
+
+.md-typeset .highlight pre {
+  max-height: var(--md-code-block-max-height);
+  overflow-y: auto;
+}
diff --git a/docs/main.py b/docs/main.py
@@ -0,0 +1,76 @@
+"""MkDocs-Macros definitions (see https://mkdocs-macros-plugin.readthedocs.io/)."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+from pathlib import Path
+
+
+def define_env(env):
+    """Register Jinja macros available as {{ macro_name(...) }} in Markdown."""
+
+    repo_root = Path(__file__).resolve().parent.parent
+
+    @env.macro
+    def embed_all_files_in_directory_as_snippets(
+        folder: str,
+        patterns: str = "*.tf,*.hcl,*.yml,*.yaml",
+    ) -> str:
+        """
+        Emit pymdownx **tabbed** blocks with **snippets** for every matching file under a directory.
+
+        ``folder`` is relative to the repo ``deployment-examples/`` directory. Snippet paths match
+        that layout; ensure ``pymdownx.snippets`` ``base_path`` includes ``../deployment-examples``.
+
+        ``patterns`` is a comma-separated list of globs matched against the **basename**
+        (e.g. ``*.tf`` or ``*`` for every file). Hidden files (names starting with ``.``) are skipped.
+        """
+        root = repo_root / "deployment-examples" / folder
+        if not root.is_dir():
+            raise FileNotFoundError(
+                f"embed_all_files_in_directory_as_snippets: not a directory: {root}"
+            )
+
+        globs = [p.strip() for p in patterns.split(",") if p.strip()]
+        if not globs:
+            globs = ["*"]
+
+        def include_file(path: Path) -> bool:
+            if path.name.startswith("."):
+                return False
+            return any(fnmatch(path.name, g) for g in globs)
+
+        paths = sorted(
+            (p for p in root.rglob("*") if p.is_file() and include_file(p)),
+            key=lambda p: p.as_posix(),
+        )
+        if not paths:
+            return "_No matching files found._"
+
+        blocks: list[str] = []
+        deploy_root = repo_root / "deployment-examples"
+        for path in paths:
+            rel = path.relative_to(deploy_root).as_posix()
+            title = path.relative_to(root).as_posix()
+            language = _fence_language(path.suffix)
+            inner_indent = "    "
+            blocks.append(f'=== "{title}"')
+            blocks.append(f"{inner_indent}```{language}")
+            blocks.append(f'{inner_indent}--8<-- "{rel}"')
+            blocks.append(f"{inner_indent}```")
+            blocks.append("")
+
+        return "\n".join(blocks).rstrip() + "\n"
+
+
+def _fence_language(suffix: str) -> str:
+    return {
+        ".tf": "hcl",
+        ".hcl": "hcl",
+        ".yml": "yaml",
+        ".yaml": "yaml",
+        ".json": "json",
+        ".md": "markdown",
+        ".sh": "bash",
+        ".txt": "text",
+    }.get(suffix.lower(), "text")
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -105,10 +105,12 @@ nav:
 
 plugins:
   - search
+  - macros
   - gen-files:
       scripts:
         - scripts/gen_helm_readme.py
         - scripts/copy_files_from_repo.py
+        - scripts/zip_deployment_examples.py
   - termynal
   - mkdocs-jupyter:
       ignore_h1_titles: True
@@ -117,11 +119,22 @@ extra:
   analytics:
     provider: custom
 
+extra_css:
+  - stylesheets/extra.css
+
 markdown_extensions:
   - admonition
   - attr_list
   - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.snippets:
+      check_paths: true
+      base_path:
+        - docs
+        # Include the deployment-examples dir to embed the terraform files
+        - ../deployment-examples
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
@@ -5,6 +5,7 @@ description = "CogStack Documentation"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
+    "mkdocs-macros-plugin>=1.3.0",
     "mkdocs-gen-files>=0.6.1",
     "mkdocs-jupyter>=0.26.1",
     "mkdocs-material>=9.7.0",

diff --git a/docs/scripts/zip_deployment_examples.py b/docs/scripts/zip_deployment_examples.py
@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+"""
+mkdocs-gen-files generator: zip archives of deployment example folders.
+
+Each zip is written under `docs_dir` so MkDocs publishes it as a static download.
+
+Configuration:
+`ZIP_SPECS` is a list of dicts with:
+- `sourceFolderPath`: directory under the repository root to archive (recursive)
+- `outputZipPath`: path (relative to MkDocs `docs_dir`) for the `.zip` file
+"""
+
+import io
+import zipfile
+from pathlib import Path
+
+import mkdocs_gen_files  # type: ignore[import-not-found]
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+ZIP_SPECS = [
+    {
+        "sourceFolderPath": "deployment-examples/aws-kubernetes",
+        "outputZipPath": "assets/downloads/deployment-examples-aws-kubernetes.zip",
+    },
+]
+
+
+def main() -> None:
+    """Build configured zips and register them with the MkDocs virtual file tree."""
+    for spec in ZIP_SPECS:
+        source_rel = spec["sourceFolderPath"]
+        output_rel = spec["outputZipPath"]
+
+        source_dir = REPO_ROOT / source_rel
+        if not source_dir.is_dir():
+            raise FileNotFoundError(f"Source directory not found: {source_dir}")
+
+        root_name = source_dir.name
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+            for path in sorted(source_dir.rglob("*"), key=lambda p: p.as_posix()):
+                if not path.is_file():
+                    continue
+                arcname = Path(root_name) / path.relative_to(source_dir)
+                zf.write(path, arcname.as_posix())
+
+        out = Path(output_rel)
+        with mkdocs_gen_files.open(out.as_posix(), "wb") as f:
+            f.write(buf.getvalue())
+        mkdocs_gen_files.set_edit_path(out.as_posix(), source_dir.relative_to(REPO_ROOT))
+
+
+main()
diff --git a/docs/uv.lock b/docs/uv.lock