Merge pull request lightspeed-core#879 from tisnik/lcore-1077-better-doc-in-scripts

LCORE-1077: better doc in scripts

Author: tisnik

scripts/gen_doc.py

@@ -11,7 +11,15 @@
 
 
 def generate_docfile(directory):
-    """Generate README.md in the CWD."""
+    """
+    Write or overwrite a README.md in the current working directory with module docstring summaries.
+
+    The file will begin with a header indicating the provided `directory` path.
+    For each `.py` file in the current working directory the function writes a
+    second-level Markdown header linking to the file, then writes the first
+    line of the module docstring if present, and finally writes the filename as
+    a separate entry.
+    """
     with open("README.md", "w", encoding="utf-8", newline="\n") as indexfile:
         print(
             f"# List of source files stored in `{directory}` directory",
@@ -36,7 +44,13 @@ def generate_docfile(directory):
 
 
 def generate_documentation_on_path(path):
-    """Generate documentation for all the sources found in path."""
+    """Generate documentation for all the sources found in path.
+
+    This function generate README.md for Python sources in the given directory.
+
+    Parameters:
+        path (str or os.PathLike): Directory in which to generate the README.md file.
+    """
     directory = path
     cwd = os.getcwd()
     os.chdir(directory)

scripts/generate_openapi_schema.py

@@ -24,7 +24,12 @@
 
 
 def read_version_from_openapi(filename: str) -> str:
-    """Read version from OpenAPI.json file."""
+    """
+    Extract the OpenAPI document's version from a generated OpenAPI JSON file.
+
+    Returns:
+        str: The value of the OpenAPI document's `info.version`.
+    """
     # retrieve pre-generated OpenAPI schema
     with open(filename, encoding="utf-8") as fin:
         pre_generated_schema = json.load(fin)
@@ -36,7 +41,12 @@ def read_version_from_openapi(filename: str) -> str:
 
 
 def read_version_from_pyproject():
-    """Read version from pyproject.toml file."""
+    """
+    Obtain the project's version using PDM (`pdm show --version`), which supports dynamic versions.
+
+    Returns:
+        str: The project version string.
+    """
     # it is not safe to just try to read version from pyproject.toml file directly
     # the PDM tool itself is able to retrieve the version, even if the version
     # is generated dynamically

scripts/query_llm.py

@@ -13,7 +13,21 @@
 
 
 def main() -> int:
-    """Entry point to this tool."""
+    """
+    CLI entry point that sends a query to a local LLM endpoint and prints the model response.
+
+    Parses command-line arguments (--query, --system-prompt, --url, --timeout),
+    POSTs a JSON payload with the query and system prompt to the configured
+    endpoint, and prints the returned "response" value followed by the request
+    elapsed time. Error diagnostics are printed to stderr.
+
+    Returns:
+        int: Exit code where
+            `0` indicates success,
+            `1` indicates an HTTP/request failure,
+            `2` indicates the server response was not valid JSON,
+            `3` indicates the JSON response did not contain a `"response"` field.
+    """
     parser = argparse.ArgumentParser(
         description="Send a query to a local LLM endpoint."
     )