diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..91fe08f --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ + +site/ diff --git a/docs/docs/cogstack-ce/_index.md b/docs/docs/cogstack-ce/_index.md index 892c14e..999bb67 100644 --- a/docs/docs/cogstack-ce/_index.md +++ b/docs/docs/cogstack-ce/_index.md @@ -27,7 +27,7 @@ It combines model serving, de-identification, model training, notebook-based ana For the full installation reference, deployment instructions, and customizations, see: -- [Deployment](../platform/deployment/_index.md) +- [Deployment](../platform/deployment/index.md) - [CogStack CE Helm chart (install + customization)](../platform/deployment/helm/charts/cogstack-ce-helm.md) ## Models diff --git a/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md b/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md index f0b53f2..cc839e1 100644 --- a/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md +++ b/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md @@ -94,6 +94,6 @@ If those outputs appear, you have validated the full end-to-end flow from Jupyte ## Next Steps -- See the [full deployment documentation](../../platform/deployment/_index.md) for more details on scaling, production security, and advanced configuration options. +- See the [full deployment documentation](../../platform/deployment/index.md) for more details on scaling, production security, and advanced configuration options. - See full install instructions of the cogstack CE chart[CogStack CE Helm chart (install + customization)](../../platform/deployment/helm/charts/cogstack-ce-helm.md) - See further tutorials on medcat on [GitHub](https://github.com/CogStack/cogstack-nlp/tree/79f00cfc204f4ae559b56c8e397bbcaf82d44274/medcat-v2-tutorials) diff --git a/docs/docs/cogstack-ce/tutorial/quickstart-installation.md b/docs/docs/cogstack-ce/tutorial/quickstart-installation.md index 95cc1b3..9e13234 100644 --- a/docs/docs/cogstack-ce/tutorial/quickstart-installation.md +++ b/docs/docs/cogstack-ce/tutorial/quickstart-installation.md @@ -24,7 +24,7 @@ This command will install Cogstack community edition with all the default values Once the initial installation is done, then any updates should be significantly faster. - The defaults are set for a production-ready environment. See [Deployment](../../platform/deployment/_index.md) for detailed deployment information and customization options. + The defaults are set for a production-ready environment. See [Deployment](../../platform/deployment/index.md) for detailed deployment information and customization options. ## Port-forward and open JupyterHub diff --git a/docs/docs/overview/getting-started.md b/docs/docs/overview/getting-started.md index 324ce29..250e989 100644 --- a/docs/docs/overview/getting-started.md +++ b/docs/docs/overview/getting-started.md @@ -20,13 +20,15 @@ Suggested order for reading the docs and getting the most out of CogStack. **If you care about running CogStack:** -- [Deployment overview](../platform/deployment/_index.md) — Ways to deploy (Helm, Docker Compose, cloud examples). +- [Deployment overview](../platform/deployment/index.md) — Ways to deploy (Helm, Docker Compose, cloud examples). - [Quickstart](../platform/deployment/get-started/quickstart.md) — Get a local instance running quickly. +- [Deployment examples](../platform/deployment/examples/index.md) — Real-world deployment scenarios for AWS, Azure, OpenStack, + ## 3. Deploy and operate - **[Helm tutorial](../platform/deployment/helm/tutorial.md)** — Deploy with Helm step by step. -- **[Observability](../platform/observability/_index.md)** — Dashboards, telemetry, and alerting for your deployment. +- **[Observability](../platform/observability/index.md)** — Dashboards, telemetry, and alerting for your deployment. ## 4. Go deeper diff --git a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md index ae17bc3..9b5bea7 100644 --- a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md +++ b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md @@ -1,5 +1,13 @@ # AWS EKS Deployment +
+ +{{ cogstack_banner_logo() }} + +:material-aws:{ .tech-icon-aws } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform } + +
+ This is an example deployment of CogStack in AWS. It will create publically accessible services, so is not suitable for production deployment. The recommended deployment in AWS is based on using Kubernetes through AWS EKS. @@ -11,12 +19,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 + +All you need to do is get the Terraform files that have been preconfigured for this example (the ZIP contains every `deployment-examples` tree; use the `aws-kubernetes` folder for this guide). + +[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.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. -### Steps +{{ embed_all_files_in_directory_as_snippets('aws-kubernetes/kubernetes-deployment') }} -### 1. Add Required Secrets for your env +### 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 +50,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 +73,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/platform/deployment/examples/azure-kubernetes-aks.md b/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md index 83a2212..9d7ee17 100644 --- a/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md +++ b/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md @@ -1,12 +1,20 @@ # Azure AKS Deployment -This is an example deployment of CogStack in Azure. +
+ +{{ cogstack_banner_logo() }} + +:material-microsoft-azure:{ .tech-icon-azure } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform } + +
+ +This is an example deployment of CogStack in Azure. The recommended deployment of CogStack in Azure is based on using Kubernetes through Azure Kubernetes Service. -This example will create a AKS cluster, setup any necessary config, deploy CogStack to the cluster, and test that it is available. It will create publically accessible services, so is not suitable for production deployment. +This example will create a AKS cluster, setup any necessary config, deploy CogStack to the cluster, and test that it is available. It will create publically accessible services, so is not suitable for production deployment. -We create a cluster following the Official Azure Verified Modules patterns in https://azure.github.io/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules/ to create AKS clusters with their recommended defaults. +We create a cluster following the Official Azure Verified Modules patterns in https://azure.github.io/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules/ to create AKS clusters with their recommended defaults. ## Usage @@ -14,7 +22,7 @@ Deployment through terraform is carried out through two terraform commands, to h ### Requirements - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install) -- Azure Credentials for an account and subscription that can create and destroy resources. +- Azure Credentials for an account and subscription that can create and destroy resources. #### Required Permissions - Contributor @@ -23,18 +31,36 @@ Deployment through terraform is carried out through two terraform commands, to h #### Required Features - EncryptionAtHost: `az feature register --namespace Microsoft.Compute --name EncryptionAtHost` -### Steps +### 1. Get the configuration files + +All you need to do is get the Terraform files that have been preconfigured for this example (this download includes every `deployment-examples` tree; use the `azure-kubernetes` folder for this guide). + +[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button } + +Alternatively you can view the file contents here: + +#### aks-cluster terraform files -### 1. Use the Azure CLI to login for your subscription -Run the az login command, which will open a web browser for you to login to your azure account. We then set the subscription ID for use by the Azure RM Terraform provider. +This terraform configuration will create a new Azure AKS cluster. + +{{ embed_all_files_in_directory_as_snippets('azure-kubernetes/aks-cluster') }} + +#### kubernetes-deployment terraform files + +This terraform configuration will use the helm provider to run services in kubernetes. + +{{ embed_all_files_in_directory_as_snippets('azure-kubernetes/kubernetes-deployment') }} + +### 2. Use the Azure CLI to login for your subscription +Run the az login command, which will open a web browser for you to login to your azure account. We then set the subscription ID for use by the Azure RM Terraform provider. ```bash az login export ARM_SUBSCRIPTION_ID=$(az account show --query id -o tsv) ``` -### 2. Run Terraform -Terraform is run on two modules, so we will run one terraform apply in one folder, then another terraform apply in a second folder. +### 3. Run Terraform +Terraform is run on two modules, so we will run one terraform apply in one folder, then another terraform apply in a second folder. Initial provisioning takes around 15 minutes. @@ -53,7 +79,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: @@ -69,8 +95,6 @@ http://localhost:5000/demo You can destroy the infra to save costs when it wont be used for a long time. -Do note that there is an initial cost every time the EKS infrastructure is created, looks to be around $0.50 at time of writing. - ```bash cd ../kubernetes-deployment terraform destroy @@ -94,7 +118,7 @@ AZURE_KUBECONFIG=$(terraform output -raw kubeconfig_file) export KUBECONFIG=${AZURE_KUBECONFIG} ``` -Note - alternatively you could use the Azure CLI to set your kubeconfig using +Note - alternatively you could use the Azure CLI to set your kubeconfig using ```bash MY_RESOURCE_GROUP_NAME=$(terraform output -raw resource_group_name) @@ -112,4 +136,4 @@ helm install my-medcat oci://registry-1.docker.io/cogstacksystems/medcat-service kubectl apply -f resources/ingress-medcat-service.yaml # Find public url kubectl get ingress -``` \ No newline at end of file +``` diff --git a/docs/docs/platform/deployment/examples/_index.md b/docs/docs/platform/deployment/examples/index.md similarity index 100% rename from docs/docs/platform/deployment/examples/_index.md rename to docs/docs/platform/deployment/examples/index.md diff --git a/docs/docs/platform/deployment/examples/openstack-docker.md b/docs/docs/platform/deployment/examples/openstack-docker.md index 090c545..d1a2ec7 100644 --- a/docs/docs/platform/deployment/examples/openstack-docker.md +++ b/docs/docs/platform/deployment/examples/openstack-docker.md @@ -1,6 +1,14 @@ # Openstack Docker Deployment -This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely. +
+ +{{ cogstack_banner_logo() }} + +:simple-openstack:{ .tech-icon-openstack } :simple-docker:{ .tech-icon-docker } :simple-portainer: :simple-ansible:{ .tech-icon-ansible } :simple-terraform:{ .tech-icon-terraform } + +
+ +This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely. This example: @@ -17,11 +25,31 @@ This example: - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install) - Openstack Cloud environment -### 1. Add Required Secrets for your env +### 1. Get the configuration files + +Get the Terraform files for this example (the ZIP contains all `deployment-examples`; use the `openstack-docker` folder for this guide). + +[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button } + +Alternatively you can view the file contents here: + +#### openstack-vms terraform files + +This module provisions OpenStack VMs and networking for the stack. + +{{ embed_all_files_in_directory_as_snippets('openstack-docker/openstack-vms') }} + +#### docker-deployment terraform files + +This module deploys Docker-based CogStack services. + +{{ embed_all_files_in_directory_as_snippets('openstack-docker/docker-deployment') }} + +### 2. Add required secrets for your environment -Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. +Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. -### 2. Run Terraform +### 3. Run Terraform ```bash terraform init @@ -30,7 +58,7 @@ terraform apply Initial provisioning takes up to 10 minutes, where time is mostly downloading large docker images -### 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/platform/deployment/examples/openstack-kubernetes-k3s.md b/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md index 311a539..fe513e9 100644 --- a/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md +++ b/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md @@ -1,6 +1,14 @@ # Openstack Kubernetes Deployment -This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely. +
+ +{{ cogstack_banner_logo() }} + +:simple-openstack:{ .tech-icon-openstack } :simple-docker:{ .tech-icon-docker } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform } + +
+ +This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely. This example: @@ -14,14 +22,33 @@ This example: - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install) - Openstack Cloud environment -### 1. Add Required Secrets for your env +### 1. Get the configuration files + +Get the Terraform files for this example (the ZIP contains all `deployment-examples`; use the `openstack-kubernetes` folder for this guide). + +[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button } + +Alternatively you can view the file contents here: + +#### k3s-cluster terraform files -Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. +This terraform configuration provisions VMs and installs k3s. -### 2. Run Terraform +{{ embed_all_files_in_directory_as_snippets('openstack-kubernetes/k3s-cluster') }} + +#### kubernetes-deployment terraform files + +This terraform configuration deploys CogStack services to the cluster. + +{{ embed_all_files_in_directory_as_snippets('openstack-kubernetes/kubernetes-deployment') }} + +### 2. Add required secrets for your environment + +Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. + +### 3. Run Terraform ```bash -# Create AKS cluster cd k3s-cluster terraform init terraform apply --auto-approve @@ -37,7 +64,7 @@ terraform apply --auto-approve Initial provisioning takes up to 10 minutes, where time is mostly downloading large docker images -### 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: @@ -72,4 +99,4 @@ Access the k8s dashboard using ``` terraform output dashboard # Find the access token kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard-kong-proxy 8443:443 -``` \ No newline at end of file +``` diff --git a/docs/docs/platform/deployment/helm/charts/_index.md b/docs/docs/platform/deployment/helm/charts/index.md similarity index 87% rename from docs/docs/platform/deployment/helm/charts/_index.md rename to docs/docs/platform/deployment/helm/charts/index.md index e505c02..62d1d9f 100644 --- a/docs/docs/platform/deployment/helm/charts/_index.md +++ b/docs/docs/platform/deployment/helm/charts/index.md @@ -6,7 +6,7 @@ - [MedCAT Service Helm](medcat-service-helm.md) - [MedCAT Trainer Helm](medcat-trainer-helm.md) - [CogStack Community Edition Helm](cogstack-ce-helm.md) -- [CogStack Observability Helm](cogstack-observability-helm.md.md) +- [CogStack Observability Helm](cogstack-observability-helm.md) ## Chart Publishing diff --git a/docs/docs/platform/deployment/helm/cogstack-helm-module.md b/docs/docs/platform/deployment/helm/cogstack-helm-module.md deleted file mode 100644 index 98798ad..0000000 --- a/docs/docs/platform/deployment/helm/cogstack-helm-module.md +++ /dev/null @@ -1,29 +0,0 @@ - -# CogStack Helm Terraform Module -This Terraform module deploys CogStack services using Helm charts on a Kubernetes cluster. - -## Example usage - -```hcl -module "cogstack_helm_services" { - source = "path_to_module" - medcat_service_values = <; flatten so flex aligns logo + icons */ +.md-typeset .tech-stack-banner > p { + display: contents; + margin: 0; +} + +.md-typeset .tech-stack-banner .twemoji { + width: var(--tech-banner-icon-size, 2.75rem); + height: var(--tech-banner-icon-size, 2.75rem); + display: inline-flex; + align-items: center; + justify-content: center; +} + +.md-typeset .tech-stack-banner .twemoji img, +.md-typeset .tech-stack-banner .twemoji svg { + width: 100%; + height: 100%; +} + +.md-typeset .tech-stack-banner .tech-stack-banner__logo-svg { + display: inline-flex; + align-items: center; + flex-shrink: 0; + height: var(--tech-banner-icon-size, 2.75rem); +} + +.md-typeset .tech-stack-banner .tech-stack-banner__logo-svg svg { + height: 100%; + width: auto; + max-width: 9rem; + display: block; +} + +/* Brand colours — use { .tech-icon-* } on each shortcode in the banner */ +.md-typeset .tech-stack-banner .twemoji.tech-icon-aws svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-aws svg { + fill: #ff9900 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-kubernetes svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-kubernetes svg { + fill: #326ce5 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-terraform svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-terraform svg { + fill: #844fba !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-azure svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-azure svg { + fill: #0078d4 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-openstack svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-openstack svg { + fill: #da1a32 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-docker svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-docker svg { + fill: #2496ed !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-ansible svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-ansible svg { + fill: #000000 !important; +} diff --git a/docs/main.py b/docs/main.py new file mode 100644 index 0000000..962965a --- /dev/null +++ b/docs/main.py @@ -0,0 +1,88 @@ +"""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 cogstack_banner_logo() -> str: + """Inline SVG for the tech-stack banner (avoids late fetch vs emoji icons).""" + docs_dir = Path(env.conf.docs_dir) + path = docs_dir / "assets" / "brand-logo-dark.svg" + svg = path.read_text(encoding="utf-8").strip() + if svg.startswith("", 1)[-1].strip() + return ( + f'{svg}' + ) + + @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 index eceeb7a..3394556 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -57,17 +57,15 @@ nav: - Platform: - Platform: platform/index.md - Deployment: - - Deployment: platform/deployment/_index.md + - Deployment: platform/deployment/index.md - Getting Started: - - Getting Started: platform/deployment/get-started/_index.md + - Overview: platform/deployment/get-started/_index.md - Quickstart: platform/deployment/get-started/quickstart.md - Helm: - - Helm: platform/deployment/helm/_index.md + - Helm: platform/deployment/helm/index.md - Tutorial: platform/deployment/helm/tutorial.md - - CogStack Helm Module: platform/deployment/helm/cogstack-helm-module.md - - Troubleshooting: platform/deployment/helm/troubleshooting.md - Charts: - - Charts Overview: platform/deployment/helm/charts/_index.md + - Charts Overview: platform/deployment/helm/charts/index.md - Cogstack CE Helm: platform/deployment/helm/charts/cogstack-ce-helm.md - MedCAT Service Helm: platform/deployment/helm/charts/medcat-service-helm.md - MedCAT Trainer Helm: platform/deployment/helm/charts/medcat-trainer-helm.md @@ -75,14 +73,14 @@ nav: - Cogstack Observability Helm: platform/deployment/helm/charts/cogstack-observability-helm.md - Cogstack JupyterHub Helm: platform/deployment/helm/charts/cogstack-jupyterhub-helm.md - Examples: - - Examples: platform/deployment/examples/_index.md + - Examples: platform/deployment/examples/index.md - AWS Kubernetes EKS: platform/deployment/examples/aws-kubernetes-eks.md - Azure Kubernetes AKS: platform/deployment/examples/azure-kubernetes-aks.md - OpenStack Kubernetes K3s: platform/deployment/examples/openstack-kubernetes-k3s.md - OpenStack Docker: platform/deployment/examples/openstack-docker.md - Docker Compose: platform/deployment/reference/docker-compose/_index.md - Observability: - - Observability: platform/observability/_index.md + - Observability: platform/observability/index.md - Getting Started: - Quickstart: platform/observability/get-started/quickstart.md - User Guide Tutorial: platform/observability/get-started/userguide-tutorial.md @@ -105,10 +103,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 +117,24 @@ extra: analytics: provider: custom +extra_css: + - stylesheets/extra.css + markdown_extensions: + - md_in_html - admonition - attr_list - pymdownx.details - pymdownx.superfences + - pymdownx.snippets: + check_paths: true + base_path: + - docs + # Repo root (e.g. Read the Docs) vs. docs/ project dir (local `cd docs && mkdocs`) + - ../deployment-examples + - 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 index b1d5f5f..111d446 100644 --- 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 new file mode 100644 index 0000000..044bc9d --- /dev/null +++ b/docs/scripts/zip_deployment_examples.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +""" +mkdocs-gen-files generator: zip archives from repository 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", + "outputZipPath": "assets/downloads/deployment-examples.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 index 0f4b9d1..5d94c77 100644 --- a/docs/uv.lock +++ b/docs/uv.lock @@ -286,6 +286,7 @@ source = { virtual = "." } dependencies = [ { name = "mkdocs-gen-files" }, { name = "mkdocs-jupyter" }, + { name = "mkdocs-macros-plugin" }, { name = "mkdocs-material" }, { name = "termynal" }, ] @@ -299,6 +300,7 @@ dev = [ requires-dist = [ { name = "mkdocs-gen-files", specifier = ">=0.6.1" }, { name = "mkdocs-jupyter", specifier = ">=0.26.1" }, + { name = "mkdocs-macros-plugin", specifier = ">=1.3.0" }, { name = "mkdocs-material", specifier = ">=9.7.0" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.12.11" }, { name = "termynal", specifier = ">=0.13.1" }, @@ -412,6 +414,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" }, ] +[[package]] +name = "hjson" +version = "3.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/82/e5/0b56d723a76ca67abadbf7fb71609fb0ea7e6926e94fcca6c65a85b36a0e/hjson-3.1.0.tar.gz", hash = "sha256:55af475a27cf83a7969c808399d7bccdec8fb836a07ddbd574587593b9cdcf75", size = 40541, upload-time = "2022-08-13T02:53:01.919Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1f/7f/13cd798d180af4bf4c0ceddeefba2b864a63c71645abc0308b768d67bb81/hjson-3.1.0-py3-none-any.whl", hash = "sha256:65713cdcf13214fb554eb8b4ef803419733f4f5e551047c9b711098ab7186b89", size = 54018, upload-time = "2022-08-13T02:52:59.899Z" }, +] + [[package]] name = "idna" version = "3.11" @@ -867,6 +878,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/93/89/eb601278b12c471235860992f5973cf3c55ca3f77d1d6127389eb045a021/mkdocs_jupyter-0.26.1-py3-none-any.whl", hash = "sha256:527242c2c8f1d30970764bbab752de41243e5703f458d8bc05336ec53828192e", size = 1459618, upload-time = "2026-03-24T15:32:46.25Z" }, ] +[[package]] +name = "mkdocs-macros-plugin" +version = "1.5.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "hjson" }, + { name = "jinja2" }, + { name = "mkdocs" }, + { name = "packaging" }, + { name = "pathspec" }, + { name = "python-dateutil" }, + { name = "pyyaml" }, + { name = "requests" }, + { name = "super-collections" }, + { name = "termcolor" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/92/15/e6a44839841ebc9c5872fa0e6fad1c3757424e4fe026093b68e9f386d136/mkdocs_macros_plugin-1.5.0.tar.gz", hash = "sha256:12aa45ce7ecb7a445c66b9f649f3dd05e9b92e8af6bc65e4acd91d26f878c01f", size = 37730, upload-time = "2025-11-13T08:08:55.545Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl", hash = "sha256:c10fabd812bf50f9170609d0ed518e54f1f0e12c334ac29141723a83c881dd6f", size = 44626, upload-time = "2025-11-13T08:08:53.878Z" }, +] + [[package]] name = "mkdocs-material" version = "9.7.1" @@ -1509,6 +1541,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f1/7b/ce1eafaf1a76852e2ec9b22edecf1daa58175c090266e9f6c64afcd81d91/stack_data-0.6.3-py3-none-any.whl", hash = "sha256:d5558e0c25a4cb0853cddad3d77da9891a08cb85dd9f9f91b9f8cd66e511e695", size = 24521, upload-time = "2023-09-30T13:58:03.53Z" }, ] +[[package]] +name = "super-collections" +version = "0.6.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "hjson" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e0/de/a0c3d1244912c260638f0f925e190e493ccea37ecaea9bbad7c14413b803/super_collections-0.6.2.tar.gz", hash = "sha256:0c8d8abacd9fad2c7c1c715f036c29f5db213f8cac65f24d45ecba12b4da187a", size = 31315, upload-time = "2025-09-30T00:37:08.067Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/17/43/47c7cf84b3bd74a8631b02d47db356656bb8dff6f2e61a4c749963814d0d/super_collections-0.6.2-py3-none-any.whl", hash = "sha256:291b74d26299e9051d69ad9d89e61b07b6646f86a57a2f5ab3063d206eee9c56", size = 16173, upload-time = "2025-09-30T00:37:07.104Z" }, +] + +[[package]] +name = "termcolor" +version = "3.3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/46/79/cf31d7a93a8fdc6aa0fbb665be84426a8c5a557d9240b6239e9e11e35fc5/termcolor-3.3.0.tar.gz", hash = "sha256:348871ca648ec6a9a983a13ab626c0acce02f515b9e1983332b17af7979521c5", size = 14434, upload-time = "2025-12-29T12:55:21.882Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl", hash = "sha256:cf642efadaf0a8ebbbf4bc7a31cec2f9b5f21a9f726f4ccbb08192c9c26f43a5", size = 7734, upload-time = "2025-12-29T12:55:20.718Z" }, +] + [[package]] name = "termynal" version = "0.13.1"