Merge pull request #444 from tisnik/lcore-581-doc-for-all-modules

LCORE-581: generated documentation for all modules

Author: tisnik

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

scripts/gen_doc.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+
+"""Generate documentation for all modules from Lightspeed Stack core service."""
+
+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)

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.
+

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.
+

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.
+

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.
+

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.
+

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.
+

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.
+

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.
+