From 0e044f8d969d561195e2404c98b17d73b5de075c Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:58:31 +0100 Subject: [PATCH 1/2] docs: avoid hiding content in section index pages Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- docs/introduction/README.md | 6 +++++- docs/introduction/_category_.json | 4 +++- docs/project-specification/00-overview.md | 4 +--- docs/project-specification/README.md | 8 ++++++-- docs/project-specification/_category_.json | 4 +++- 5 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/introduction/README.md b/docs/introduction/README.md index 1245f518..7708a717 100644 --- a/docs/introduction/README.md +++ b/docs/introduction/README.md @@ -1,4 +1,8 @@ -# Overview +--- +sidebar_position: 0 +--- + +# What is Topo? Topo helps you discover, configure, and deploy containerized software to Arm-based Linux devices over SSH. It uses Compose projects, container images, and standard container tools. diff --git a/docs/introduction/_category_.json b/docs/introduction/_category_.json index 3fca6fb9..56dd5e5f 100644 --- a/docs/introduction/_category_.json +++ b/docs/introduction/_category_.json @@ -1,3 +1,5 @@ { - "position": 0 + "label": "Introduction", + "position": 0, + "link": null } diff --git a/docs/project-specification/00-overview.md b/docs/project-specification/00-overview.md index 939b83c8..16da6d69 100644 --- a/docs/project-specification/00-overview.md +++ b/docs/project-specification/00-overview.md @@ -1,6 +1,4 @@ -# Overview - -A Topo Project is a repository that defines one or more container services using the [Compose Spec](https://compose-spec.io) with Topo-specific metadata. +# Project Overview ## Requirements diff --git a/docs/project-specification/README.md b/docs/project-specification/README.md index 6af59ef4..7676743b 100644 --- a/docs/project-specification/README.md +++ b/docs/project-specification/README.md @@ -1,4 +1,8 @@ -# Project Specification +--- +sidebar_position: -1 +--- + +# What is a Topo Project? A Topo Project is a containerized sample project for Arm-based Linux systems. At minimum, it is a directory containing a `compose.yaml`, Dockerfiles, and source code, with an `x-topo` metadata block that describes what the Project does, what hardware features it requires, and what parameters a user can configure. @@ -35,7 +39,7 @@ Because this is valid Compose, any Project can be run with plain `docker compose ## Specification - Human-readable spec: - - [Overview](00-overview.md) + - [Project Overview](00-overview.md) - [Authoring Topo Projects](01-authoring-projects.md) - [Project Configuration](02-project-configuration.md) - [Schema Compliance](03-schema.md) diff --git a/docs/project-specification/_category_.json b/docs/project-specification/_category_.json index 818afe30..b9dd4ecc 100644 --- a/docs/project-specification/_category_.json +++ b/docs/project-specification/_category_.json @@ -1,3 +1,5 @@ { - "position": 1 + "label": "Project Specification", + "position": 1, + "link": null } From 6e21d24cceae91cce7be1a894d238cafc8b1edaf Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Thu, 16 Jul 2026 16:22:31 +0100 Subject: [PATCH 2/2] delete duplicate overview page Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- docs/introduction/README.md | 2 +- docs/project-specification/00-overview.md | 126 ------------------ docs/project-specification/README.md | 7 +- skills/_shared/topo-project-context.md | 2 +- .../references/topo-project-context.md | 2 +- .../references/topo-project-context.md | 2 +- .../references/topo-project-context.md | 2 +- .../references/topo-project-context.md | 2 +- 8 files changed, 9 insertions(+), 136 deletions(-) delete mode 100644 docs/project-specification/00-overview.md diff --git a/docs/introduction/README.md b/docs/introduction/README.md index 7708a717..45cd43e0 100644 --- a/docs/introduction/README.md +++ b/docs/introduction/README.md @@ -2,7 +2,7 @@ sidebar_position: 0 --- -# What is Topo? +# Overview Topo helps you discover, configure, and deploy containerized software to Arm-based Linux devices over SSH. It uses Compose projects, container images, and standard container tools. diff --git a/docs/project-specification/00-overview.md b/docs/project-specification/00-overview.md deleted file mode 100644 index 16da6d69..00000000 --- a/docs/project-specification/00-overview.md +++ /dev/null @@ -1,126 +0,0 @@ -# Project Overview - -## Requirements - -- _Must_ Contain a Compose Spec file named `compose.yaml`, which: - - _Should_ contain a `x-topo` attribute defining the required fields - - see [x-topo schema](#x-topo-schema) - - _Must_ define one or more valid [services](https://github.com/compose-spec/compose-spec/blob/main/05-services.md) - - _Must_ set `platform: linux/arm64` on every service unless that service uses Remoteproc Runtime -- _Could_ Be a git repo - -## Examples - -### Single Service Project - -A Project that builds a single container image: - -**compose.yaml** - -```yaml -# standard https://github.com/compose-spec/compose-spec/blob/main/05-services.md -services: - app: - platform: linux/arm64 - build: - context: . - -# Topo-specific metadata -x-topo: - name: "kleidi-llm" # Required - description: | - Run an LLM locally using KleidiAI optimised inference on Arm CPU - features: - - "SME" - - "NEON" -``` - -### Multi-Service Project - -A Project that composes multiple services, which can extend other Projects or use public images: - -**compose.yaml** - -```yaml -# standard https://github.com/compose-spec/compose-spec/ -services: - # A service that extends another Project - cool-service: - extends: - file: ./cool-service-project/compose.yaml - service: cool-service - build: - args: - MODEL: "llama-3.1-8b" - QUANTIZATION: "q4_0" - # A service using a public container image - open-webui: - platform: linux/arm64 - image: ghcr.io/open-webui/open-webui:main - -# Topo-specific metadata -x-topo: - name: "kleidi-llm-webui" - description: | - Run an LLM chat web app with Kleidi inference - features: - - "SME" - - "NEON" -``` - -This allows Projects to be runnable with plain `docker compose` while Implementations can add customization and local development workflows. - -## Spec Examples - -- [Hello World](https://github.com/Arm-Examples/topo-welcome) -- [Lightbulb Moment](https://github.com/Arm-Examples/topo-lightbulb-moment) -- [Topo llama.cpp WebUI Chat](https://github.com/Arm-Examples/topo-llama-web-ui) -- [SIMD Visual Benchmark](https://github.com/Arm-Examples/topo-simd-visual-benchmark) - -## Use Cases - -- A Zephyr starter program compatible with [Remoteproc Runtime](https://github.com/arm/remoteproc-runtime) -- An LLM model running on an Arm-SIMD optimised (e.g. KleidiAI) inference back-end -- A Project with one service running on the primary OS and another running on a remote processor, with both services co-ordinating over RPMsg - -## x-topo Schema - -The `x-topo` extension provides metadata for Projects. If included, it must be specified at the root level of a [Compose file](https://compose-spec.io). - -### Example - -```yaml -x-topo: - name: string # Required - description: string # Optional - features: [string] # Optional - deployment_success_message: string # Optional - parameters: # Optional - : - description: string # Optional - required: boolean # Optional - default: string # Optional - example: string # Optional -``` - -### Fields - -**`name`** (string, required) -Unique identifier for the Project. - -**`description`** (string, optional) -Multiline human-readable explanation of what the Project does. - -**`features`** (array of strings, optional) -Target features required or utilised by the Project (e.g., `SVE`, `NEON`, `SME`). - -**`deploy_success_message`** (string, optional) -Message displayed to the user after a successful deployment. If omitted, a default message is shown. - -**`parameters`** (object, optional) -Dictionary of project parameter definitions. Each key is a parameter name (e.g., `GREETING`) with the following properties: - -- **`description`** (string, optional) — Context displayed in user prompts -- **`required`** (boolean, optional) — If `true`, Implementations must enforce input or error -- **`default`** (string, optional) — Value used if user skips input (only valid when not required) -- **`example`** (string, optional) — Hint text displayed in help and prompts diff --git a/docs/project-specification/README.md b/docs/project-specification/README.md index 7676743b..776d4d56 100644 --- a/docs/project-specification/README.md +++ b/docs/project-specification/README.md @@ -1,8 +1,8 @@ --- -sidebar_position: -1 +sidebar_position: 0 --- -# What is a Topo Project? +# Overview A Topo Project is a containerized sample project for Arm-based Linux systems. At minimum, it is a directory containing a `compose.yaml`, Dockerfiles, and source code, with an `x-topo` metadata block that describes what the Project does, what hardware features it requires, and what parameters a user can configure. @@ -39,12 +39,11 @@ Because this is valid Compose, any Project can be run with plain `docker compose ## Specification - Human-readable spec: - - [Project Overview](00-overview.md) - [Authoring Topo Projects](01-authoring-projects.md) - [Project Configuration](02-project-configuration.md) - [Schema Compliance](03-schema.md) - Machine-readable schema: - - [`schema/topo-project-specification.json`](schema/topo-project-specification.json) + - [`schema/topo-project-specification.json`](https://github.com/arm/topo/blob/main/docs/project-specification/schema/topo-project-specification.json) ## Discover Topo Projects diff --git a/skills/_shared/topo-project-context.md b/skills/_shared/topo-project-context.md index 97f4486d..71a6c377 100644 --- a/skills/_shared/topo-project-context.md +++ b/skills/_shared/topo-project-context.md @@ -15,7 +15,7 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `00-overview.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. diff --git a/skills/topo-project-bootstrap/references/topo-project-context.md b/skills/topo-project-bootstrap/references/topo-project-context.md index 97f4486d..71a6c377 100644 --- a/skills/topo-project-bootstrap/references/topo-project-context.md +++ b/skills/topo-project-bootstrap/references/topo-project-context.md @@ -15,7 +15,7 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `00-overview.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. diff --git a/skills/topo-project-context/references/topo-project-context.md b/skills/topo-project-context/references/topo-project-context.md index 97f4486d..71a6c377 100644 --- a/skills/topo-project-context/references/topo-project-context.md +++ b/skills/topo-project-context/references/topo-project-context.md @@ -15,7 +15,7 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `00-overview.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. diff --git a/skills/topo-project-lint/references/topo-project-context.md b/skills/topo-project-lint/references/topo-project-context.md index 97f4486d..71a6c377 100644 --- a/skills/topo-project-lint/references/topo-project-context.md +++ b/skills/topo-project-lint/references/topo-project-context.md @@ -15,7 +15,7 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `00-overview.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension. diff --git a/skills/topo-project-optimize-deployment/references/topo-project-context.md b/skills/topo-project-optimize-deployment/references/topo-project-context.md index 97f4486d..71a6c377 100644 --- a/skills/topo-project-optimize-deployment/references/topo-project-context.md +++ b/skills/topo-project-optimize-deployment/references/topo-project-context.md @@ -15,7 +15,7 @@ Use Topo vocabulary precisely: Refresh spec-sensitive context at runtime before making or validating Project changes. Authoritative references, in order: - Published Topo Project Specification schema: `https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json`. -- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `00-overview.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. +- Published Topo Project Specification docs: `https://github.com/arm/topo/docs/project-specification`, especially `README.md`, `01-authoring-projects.md`, `02-project-configuration.md`, and `03-schema.md`. - Published Topo glossary for domain terms: `https://github.com/arm/topo/blob/main/docs/introduction/glossary.md`. - Compose Spec for standard Compose semantics. Do not invent non-standard Compose keys except the root-level `x-topo` extension.