From 5b4e4850b5ef49465f3b877942817e090e1ca1a3 Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Mon, 25 Aug 2025 09:51:13 +0200 Subject: [PATCH 1/3] Script to generate documentation for all modules --- scripts/gen_doc.py | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100755 scripts/gen_doc.py diff --git a/scripts/gen_doc.py b/scripts/gen_doc.py new file mode 100755 index 00000000..d775a87e --- /dev/null +++ b/scripts/gen_doc.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 + +import os + +import ast +from pathlib import Path + + +for path in Path("src").rglob("*"): + if path.is_dir(): + directory = path + cwd = os.getcwd() + os.chdir(directory) + print(directory) + + try: + with open("README.md", "w", encoding="utf-8", newline="\n") as indexfile: + print(f"# List of source files stored in `{directory}` directory", file=indexfile) + print("", file=indexfile) + files = sorted(os.listdir()) + + for file in files: + if file.endswith(".py"): + print(f"## [{file}]({file})", file=indexfile) + with open(file, "r", encoding="utf-8") as fin: + source = fin.read() + try: + mod = ast.parse(source) + doc = ast.get_docstring(mod) + except SyntaxError: + doc = None + if doc: + print(doc.splitlines()[0], file=indexfile) + print(file=indexfile) + finally: + os.chdir(cwd) From 7743e5ce5f7693651798a96cc6eea8322e72dff3 Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Mon, 25 Aug 2025 09:51:40 +0200 Subject: [PATCH 2/3] Generated doc --- src/app/README.md | 14 +++++++++++++ src/app/endpoints/README.md | 38 +++++++++++++++++++++++++++++++++++ src/auth/README.md | 23 +++++++++++++++++++++ src/metrics/README.md | 8 ++++++++ src/models/README.md | 14 +++++++++++++ src/models/database/README.md | 11 ++++++++++ src/runners/README.md | 8 ++++++++ src/utils/README.md | 29 ++++++++++++++++++++++++++ 8 files changed, 145 insertions(+) create mode 100644 src/app/README.md create mode 100644 src/app/endpoints/README.md create mode 100644 src/auth/README.md create mode 100644 src/metrics/README.md create mode 100644 src/models/README.md create mode 100644 src/models/database/README.md create mode 100644 src/runners/README.md create mode 100644 src/utils/README.md diff --git a/src/app/README.md b/src/app/README.md new file mode 100644 index 00000000..5fd8395f --- /dev/null +++ b/src/app/README.md @@ -0,0 +1,14 @@ +# List of source files stored in `src/app` directory + +## [__init__.py](__init__.py) +REST API service based on FastAPI. + +## [database.py](database.py) +Database engine management. + +## [main.py](main.py) +Definition of FastAPI based web service. + +## [routers.py](routers.py) +REST API routers. + diff --git a/src/app/endpoints/README.md b/src/app/endpoints/README.md new file mode 100644 index 00000000..0dd0cea0 --- /dev/null +++ b/src/app/endpoints/README.md @@ -0,0 +1,38 @@ +# List of source files stored in `src/app/endpoints` directory + +## [__init__.py](__init__.py) +Implementation of all endpoints. + +## [authorized.py](authorized.py) +Handler for REST API call to authorized endpoint. + +## [config.py](config.py) +Handler for REST API call to retrieve service configuration. + +## [conversations.py](conversations.py) +Handler for REST API calls to manage conversation history. + +## [feedback.py](feedback.py) +Handler for REST API endpoint for user feedback. + +## [health.py](health.py) +Handlers for health REST API endpoints. + +## [info.py](info.py) +Handler for REST API call to provide info. + +## [metrics.py](metrics.py) +Handler for REST API call to provide metrics. + +## [models.py](models.py) +Handler for REST API call to list available models. + +## [query.py](query.py) +Handler for REST API call to provide answer to query. + +## [root.py](root.py) +Handler for the / endpoint. + +## [streaming_query.py](streaming_query.py) +Handler for REST API call to provide answer to streaming query. + diff --git a/src/auth/README.md b/src/auth/README.md new file mode 100644 index 00000000..0b4f1236 --- /dev/null +++ b/src/auth/README.md @@ -0,0 +1,23 @@ +# List of source files stored in `src/auth` directory + +## [__init__.py](__init__.py) +This package contains authentication code and modules. + +## [interface.py](interface.py) +Abstract base class for all authentication method implementations. + +## [jwk_token.py](jwk_token.py) +Manage authentication flow for FastAPI endpoints with JWK based JWT auth. + +## [k8s.py](k8s.py) +Manage authentication flow for FastAPI endpoints with K8S/OCP. + +## [noop.py](noop.py) +Manage authentication flow for FastAPI endpoints with no-op auth. + +## [noop_with_token.py](noop_with_token.py) +Manage authentication flow for FastAPI endpoints with no-op auth and provided user token. + +## [utils.py](utils.py) +Authentication utility functions. + diff --git a/src/metrics/README.md b/src/metrics/README.md new file mode 100644 index 00000000..6f09eef3 --- /dev/null +++ b/src/metrics/README.md @@ -0,0 +1,8 @@ +# List of source files stored in `src/metrics` directory + +## [__init__.py](__init__.py) +Metrics module for Lightspeed Stack. + +## [utils.py](utils.py) +Utility functions for metrics handling. + diff --git a/src/models/README.md b/src/models/README.md new file mode 100644 index 00000000..b7bd2510 --- /dev/null +++ b/src/models/README.md @@ -0,0 +1,14 @@ +# List of source files stored in `src/models` directory + +## [__init__.py](__init__.py) +Pydantic models. + +## [config.py](config.py) +Model with service configuration. + +## [requests.py](requests.py) +Models for REST API requests. + +## [responses.py](responses.py) +Models for REST API responses. + diff --git a/src/models/database/README.md b/src/models/database/README.md new file mode 100644 index 00000000..09128c43 --- /dev/null +++ b/src/models/database/README.md @@ -0,0 +1,11 @@ +# List of source files stored in `src/models/database` directory + +## [__init__.py](__init__.py) +Database models package. + +## [base.py](base.py) +Base model for SQLAlchemy ORM classes. + +## [conversations.py](conversations.py) +User conversation models. + diff --git a/src/runners/README.md b/src/runners/README.md new file mode 100644 index 00000000..4f9d04bf --- /dev/null +++ b/src/runners/README.md @@ -0,0 +1,8 @@ +# List of source files stored in `src/runners` directory + +## [__init__.py](__init__.py) +Runners. + +## [uvicorn.py](uvicorn.py) +Uvicorn runner. + diff --git a/src/utils/README.md b/src/utils/README.md new file mode 100644 index 00000000..ba6eb50d --- /dev/null +++ b/src/utils/README.md @@ -0,0 +1,29 @@ +# List of source files stored in `src/utils` directory + +## [__init__.py](__init__.py) +Utils. + +## [checks.py](checks.py) +Checks that are performed to configuration options. + +## [common.py](common.py) +Common utilities for the project. + +## [endpoints.py](endpoints.py) +Utility functions for endpoint handlers. + +## [llama_stack_version.py](llama_stack_version.py) +Check if the Llama Stack version is supported by the LCS. + +## [mcp_headers.py](mcp_headers.py) +MCP headers handling. + +## [suid.py](suid.py) +Session ID utility functions. + +## [transcripts.py](transcripts.py) +Transcript handling. + +## [types.py](types.py) +Common types for the project. + From 8c9c7364a601b53a40b2a4e2596053f5f80bedcc Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Mon, 25 Aug 2025 10:00:33 +0200 Subject: [PATCH 3/3] Added new Makefile target --- Makefile | 3 +++ scripts/gen_doc.py | 7 ++++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 112ad003..40e6f27d 100644 --- a/Makefile +++ b/Makefile @@ -43,6 +43,9 @@ openapi-doc: docs/openapi.json ## Generate OpenAPI documentation requirements.txt: pyproject.toml pdm.lock ## Generate requirements.txt file containing hashes for all non-devel packages pdm export --prod --format requirements --output requirements.txt --no-extras --without evaluation +doc: + scripts/gen_doc.py + docs/config.puml: src/models/config.py ## Generate PlantUML class diagram for configuration pyreverse src/models/config.py --output puml --output-directory=docs/ mv docs/classes.puml docs/config.puml diff --git a/scripts/gen_doc.py b/scripts/gen_doc.py index d775a87e..d6a1242c 100755 --- a/scripts/gen_doc.py +++ b/scripts/gen_doc.py @@ -1,5 +1,7 @@ #!/usr/bin/env python3 +"""Generate documentation for all modules from Lightspeed Stack core service.""" + import os import ast @@ -15,7 +17,10 @@ try: with open("README.md", "w", encoding="utf-8", newline="\n") as indexfile: - print(f"# List of source files stored in `{directory}` directory", file=indexfile) + print( + f"# List of source files stored in `{directory}` directory", + file=indexfile, + ) print("", file=indexfile) files = sorted(os.listdir())