From d731ce76315591f1839f49d43678a38b7af7761b Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Fri, 17 Jul 2026 10:06:57 +0200 Subject: [PATCH 1/3] LCORE-2933: Developer doc --- docs/README.md | 52 +++++++----------- docs/{ => devel_doc}/ARCHITECTURE.md | 0 docs/{ => devel_doc}/architecture.png | Bin docs/{ => devel_doc}/architecture.svg | 0 .../container_orchestration.md | 0 docs/{ => devel_doc}/contributing_guide.md | 0 docs/{ => devel_doc}/conversations_api.md | 0 docs/{ => devel_doc}/installation_linux.md | 0 docs/{ => devel_doc}/installation_macos.md | 0 docs/{ => devel_doc}/openapi.json | 0 docs/{ => devel_doc}/openapi.md | 0 docs/{ => devel_doc}/providers.md | 0 docs/index.md | 52 +++++++----------- docs/{ => maintenance}/version_status.md | 0 docs/{ => maintenance}/version_status.puml | 0 docs/{ => maintenance}/version_status.svg | 0 docs/{ => maintenance}/versions_supported.md | 0 .../{ => maintenance}/versions_unsupported.md | 0 18 files changed, 42 insertions(+), 62 deletions(-) rename docs/{ => devel_doc}/ARCHITECTURE.md (100%) rename docs/{ => devel_doc}/architecture.png (100%) rename docs/{ => devel_doc}/architecture.svg (100%) rename docs/{ => devel_doc}/container_orchestration.md (100%) rename docs/{ => devel_doc}/contributing_guide.md (100%) rename docs/{ => devel_doc}/conversations_api.md (100%) rename docs/{ => devel_doc}/installation_linux.md (100%) rename docs/{ => devel_doc}/installation_macos.md (100%) rename docs/{ => devel_doc}/openapi.json (100%) rename docs/{ => devel_doc}/openapi.md (100%) rename docs/{ => devel_doc}/providers.md (100%) rename docs/{ => maintenance}/version_status.md (100%) rename docs/{ => maintenance}/version_status.puml (100%) rename docs/{ => maintenance}/version_status.svg (100%) rename docs/{ => maintenance}/versions_supported.md (100%) rename docs/{ => maintenance}/versions_unsupported.md (100%) diff --git a/docs/README.md b/docs/README.md index 6974cc434..e37225ed6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,14 +9,10 @@ See the full documentation at [`../README.md`](../README.md) or browse sub-pages * [Basic info](#basic-info) * [User docs](#user-docs) -* [Overview](#overview) -* [Installation and configuration](#installation-and-configuration) -* [Status of Lightspeed Core Stack versions](#status-of-lightspeed-core-stack-versions) +* [Developer doc](#developer-doc) + * [API](#api) +* [Maintenance](#maintenance) * [Migration guides](#migration-guides) -* [Info for developers](#info-for-developers) -* [API](#api) -* [RAG and BYOK](#rag-and-byok) -* [Other features](#other-features) * [Models](#models) * [Design documents](#design-documents) * [Agent skills](#agent-skills) @@ -58,53 +54,47 @@ See the full documentation at [`../README.md`](../README.md) or browse sub-pages [User data collection](https://lightspeed-core.github.io/lightspeed-stack/user_doc/user_data_collection.html) -## Overview +## Developer doc -[Architecture](https://lightspeed-core.github.io/lightspeed-stack/ARCHITECTURE.html) +[Architecture](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/ARCHITECTURE.html) -[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/architecture.svg) +[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/architecture.svg) -## Installation and configuration +[Installation on Linux](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/installation_linux.html) +[Installation on MacOS](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/installation_macos.html) -[Container Orchestration Guide](https://lightspeed-core.github.io/lightspeed-stack/container_orchestration.html) - -[Linux](https://lightspeed-core.github.io/lightspeed-stack/installation_linux.html) - -[MacOS](https://lightspeed-core.github.io/lightspeed-stack/installation_macos.html) +[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html) -## Status of Lightspeed Core Stack versions +[Providers](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/providers.html) -[Status of Lightspeed Core Stack versions](https://lightspeed-core.github.io/lightspeed-stack/version_status.html) +[Container Orchestration Guide](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/container_orchestration.html) -[Supported versions](https://lightspeed-core.github.io/lightspeed-stack/versions_supported.html) +[Contributing guide](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/contributing_guide.html) -[Unsupported versions](https://lightspeed-core.github.io/lightspeed-stack/versions_unsupported.html) +### API -## Migration guides +[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/openapi.html) -[Migration guides](https://lightspeed-core.github.io/lightspeed-stack/migrations/) +[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/conversations_api.html) -## Info for developers -[Contributing guide](https://lightspeed-core.github.io/lightspeed-stack/contributing_guide.html) +## Maintenance -## API +[Status of Lightspeed Core Stack versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/version_status.html) -[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/openapi.html) +[Supported versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/versions_supported.html) -[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/conversations_api.html) +[Unsupported versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/versions_unsupported.html) -## RAG and BYOK +## Migration guides -## Other features +[Migration guides](https://lightspeed-core.github.io/lightspeed-stack/migrations/) -[Providers](https://lightspeed-core.github.io/lightspeed-stack/providers.html) [Sentry error tracking](https://lightspeed-core.github.io/lightspeed-stack/sentry.html) -[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html) ## Models diff --git a/docs/ARCHITECTURE.md b/docs/devel_doc/ARCHITECTURE.md similarity index 100% rename from docs/ARCHITECTURE.md rename to docs/devel_doc/ARCHITECTURE.md diff --git a/docs/architecture.png b/docs/devel_doc/architecture.png similarity index 100% rename from docs/architecture.png rename to docs/devel_doc/architecture.png diff --git a/docs/architecture.svg b/docs/devel_doc/architecture.svg similarity index 100% rename from docs/architecture.svg rename to docs/devel_doc/architecture.svg diff --git a/docs/container_orchestration.md b/docs/devel_doc/container_orchestration.md similarity index 100% rename from docs/container_orchestration.md rename to docs/devel_doc/container_orchestration.md diff --git a/docs/contributing_guide.md b/docs/devel_doc/contributing_guide.md similarity index 100% rename from docs/contributing_guide.md rename to docs/devel_doc/contributing_guide.md diff --git a/docs/conversations_api.md b/docs/devel_doc/conversations_api.md similarity index 100% rename from docs/conversations_api.md rename to docs/devel_doc/conversations_api.md diff --git a/docs/installation_linux.md b/docs/devel_doc/installation_linux.md similarity index 100% rename from docs/installation_linux.md rename to docs/devel_doc/installation_linux.md diff --git a/docs/installation_macos.md b/docs/devel_doc/installation_macos.md similarity index 100% rename from docs/installation_macos.md rename to docs/devel_doc/installation_macos.md diff --git a/docs/openapi.json b/docs/devel_doc/openapi.json similarity index 100% rename from docs/openapi.json rename to docs/devel_doc/openapi.json diff --git a/docs/openapi.md b/docs/devel_doc/openapi.md similarity index 100% rename from docs/openapi.md rename to docs/devel_doc/openapi.md diff --git a/docs/providers.md b/docs/devel_doc/providers.md similarity index 100% rename from docs/providers.md rename to docs/devel_doc/providers.md diff --git a/docs/index.md b/docs/index.md index 2a17e7181..e92ba0164 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,14 +16,10 @@ product questions using backend LLM services, agents, and RAG databases. * [Basic info](#basic-info) * [User docs](#user-docs) -* [Overview](#overview) -* [Installation and configuration](#installation-and-configuration) -* [Status of Lightspeed Core Stack versions](#status-of-lightspeed-core-stack-versions) +* [Developer doc](#developer-doc) + * [API](#api) +* [Maintenance](#maintenance) * [Migration guides](#migration-guides) -* [Info for developers](#info-for-developers) -* [API](#api) -* [RAG and BYOK](#rag-and-byok) -* [Other features](#other-features) * [Models](#models) * [Design documents](#design-documents) * [Agent skills](#agent-skills) @@ -65,53 +61,47 @@ product questions using backend LLM services, agents, and RAG databases. [User data collection](https://lightspeed-core.github.io/lightspeed-stack/user_doc/user_data_collection.html) -## Overview +## Developer doc -[Architecture](https://lightspeed-core.github.io/lightspeed-stack/ARCHITECTURE.html) +[Architecture](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/ARCHITECTURE.html) -[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/architecture.svg) +[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/architecture.svg) -## Installation and configuration +[Installation on Linux](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/installation_linux.html) +[Installation on MacOS](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/installation_macos.html) -[Container Orchestration Guide](https://lightspeed-core.github.io/lightspeed-stack/container_orchestration.html) - -[Linux](https://lightspeed-core.github.io/lightspeed-stack/installation_linux.html) - -[MacOS](https://lightspeed-core.github.io/lightspeed-stack/installation_macos.html) +[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html) -## Status of Lightspeed Core Stack versions +[Providers](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/providers.html) -[Status of Lightspeed Core Stack versions](https://lightspeed-core.github.io/lightspeed-stack/version_status.html) +[Container Orchestration Guide](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/container_orchestration.html) -[Supported versions](https://lightspeed-core.github.io/lightspeed-stack/versions_supported.html) +[Contributing guide](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/contributing_guide.html) -[Unsupported versions](https://lightspeed-core.github.io/lightspeed-stack/versions_unsupported.html) +### API -## Migration guides +[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/openapi.html) -[Migration guides](https://lightspeed-core.github.io/lightspeed-stack/migrations/) +[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/devel_doc/conversations_api.html) -## Info for developers -[Contributing guide](https://lightspeed-core.github.io/lightspeed-stack/contributing_guide.html) +## Maintenance -## API +[Status of Lightspeed Core Stack versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/version_status.html) -[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/openapi.html) +[Supported versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/versions_supported.html) -[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/conversations_api.html) +[Unsupported versions](https://lightspeed-core.github.io/lightspeed-stack/maintenance/versions_unsupported.html) -## RAG and BYOK +## Migration guides -## Other features +[Migration guides](https://lightspeed-core.github.io/lightspeed-stack/migrations/) -[Providers](https://lightspeed-core.github.io/lightspeed-stack/providers.html) [Sentry error tracking](https://lightspeed-core.github.io/lightspeed-stack/sentry.html) -[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html) ## Models diff --git a/docs/version_status.md b/docs/maintenance/version_status.md similarity index 100% rename from docs/version_status.md rename to docs/maintenance/version_status.md diff --git a/docs/version_status.puml b/docs/maintenance/version_status.puml similarity index 100% rename from docs/version_status.puml rename to docs/maintenance/version_status.puml diff --git a/docs/version_status.svg b/docs/maintenance/version_status.svg similarity index 100% rename from docs/version_status.svg rename to docs/maintenance/version_status.svg diff --git a/docs/versions_supported.md b/docs/maintenance/versions_supported.md similarity index 100% rename from docs/versions_supported.md rename to docs/maintenance/versions_supported.md diff --git a/docs/versions_unsupported.md b/docs/maintenance/versions_unsupported.md similarity index 100% rename from docs/versions_unsupported.md rename to docs/maintenance/versions_unsupported.md From a5597c9f6566da781a7b95624be0e4afe8b4e3eb Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Fri, 17 Jul 2026 10:10:39 +0200 Subject: [PATCH 2/3] Updated path --- .github/workflows/openapi_spectral.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/openapi_spectral.yaml b/.github/workflows/openapi_spectral.yaml index 6ca05d2ae..3d0b7b0e4 100644 --- a/.github/workflows/openapi_spectral.yaml +++ b/.github/workflows/openapi_spectral.yaml @@ -26,12 +26,12 @@ jobs: - name: Install PDM # scripts/generate_openapi_schema.py asserts OpenAPI info.version matches `pdm show --version`. run: uv pip install pdm - - name: Verify docs/openapi.json matches generator + - name: Verify docs/devel_doc/openapi.json matches generator run: | set -euo pipefail uv run python scripts/generate_openapi_schema.py /tmp/openapi-generated.json - if ! diff -u docs/openapi.json /tmp/openapi-generated.json; then - echo "::error::docs/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json" + if ! diff -u docs/devel_doc/openapi.json /tmp/openapi-generated.json; then + echo "::error::docs/devel_doc/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/devel_doc/openapi.json" exit 1 fi - name: Setup Node.js @@ -39,4 +39,4 @@ jobs: with: node-version: "22" - name: Spectral lint - run: npx --yes @stoplight/spectral-cli@6 lint docs/openapi.json --fail-severity error --display-only-failures + run: npx --yes @stoplight/spectral-cli@6 lint docs/devel_doc/openapi.json --fail-severity error --display-only-failures From 09cf57da757b297d49215001bfba7f926c55892f Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Fri, 17 Jul 2026 10:39:20 +0200 Subject: [PATCH 3/3] Updated path in integration test --- tests/integration/test_openapi_json.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/integration/test_openapi_json.py b/tests/integration/test_openapi_json.py index d72869f10..7d85861e3 100644 --- a/tests/integration/test_openapi_json.py +++ b/tests/integration/test_openapi_json.py @@ -18,7 +18,7 @@ # * presence of paths/methods and key response codes # * presence and key attributes of important component schemas (enums, required fields) -OPENAPI_FILE = "docs/openapi.json" +OPENAPI_FILE = "docs/devel_doc/openapi.json" URL = "/openapi.json"