docs(servers): updated the docstrings

.pre-commit-config.yaml

@@ -48,7 +48,7 @@ repos:
         name: deptry (uv)
         language: system
         pass_filenames: false # deptry expects a project path, not filenames
-        entry: uv run deptry .
+        entry: uv run deptry --per-rule-ignores "DEP003=plum,DEP004=quartodoc|numpydoc" .
 
       - id: forbid-new-init
         name: Check if __init__.py is added to the src folder

src/classifai/servers/__init__.py

@@ -1,10 +1,17 @@
 """This module provides functionality for creating or extending a REST-API service
-which allows a user to call the search methods of one or more VectorStore objects,
+which allows a user to call the search methods of one or more `VectorStore` objects,
 from an API endpoint.
 
-These functions interact with the ClassifAI Indexer module's VectorStore objects,
+These functions interact with the ClassifAI Indexer module's `VectorStore` objects,
 such that their `embed`, `search` and `reverse_search` methods are exposed on
-REST-API endpoints, via a FastAPI service.
+REST-API endpoints, via a `FastAPI` app.
+
+
+Full API documentation for FastAPI endpoints and Pydantic Models
+can be found in autogenerated app Yammer docs at `/docs`. To do this without providing
+your own data run the initial demo to make a test `VectorStore`with `/DEMO/general_workflow_demo.ipynb`
+then run it as a demo server at `/DEMO/general_workflow_serve.py`.
+
 """
 
 from .main import get_router, get_server, make_endpoints, run_server

src/classifai/servers/main.py

@@ -37,18 +37,18 @@
 
 
 def get_router(vector_stores: list[VectorStore], endpoint_names: list[str]) -> APIRouter:
-    """Create and return a FastAPI router with search endpoints.
+    """Create and return a `FastAPI.APIRouter` with search endpoints.
 
     Args:
-        vector_stores (list[VectorStore]): A list of vector store objects, each responsible for handling embedding and search operations for a specific endpoint.
+        vector_stores (list[VectorStore]): A list of `VectorStore` objects, each responsible for handling embedding and search operations for a specific endpoint.
         endpoint_names (list[str]): A list of endpoint names corresponding to the vector stores.
 
     Returns:
         APIRouter: Router with intialized search endpoints
 
     Raises:
-        DataValidationError: If the input parameters are invalid.
-        ConfigurationError: If a vector store is missing required methods.
+        DataValidationError: Raised if the input parameters are invalid.
+        ConfigurationError: Raised if a `vector_store` is missing required methods.
 
     """
     # ---- Validate startup args -> DataValidationError / ConfigurationError
@@ -105,11 +105,11 @@ def docs():
 
 
 def get_server(vector_stores: list[VectorStore], endpoint_names: list[str]) -> FastAPI:
-    """Create and return a FastAPI server with search endpoints.
+    """Create and return a `FastAPI` server with search endpoints.
 
     Args:
-        vector_stores (list[VectorStore]): A list of vector store objects, each responsible for handling embedding and search operations for a specific endpoint.
-        endpoint_names (list[str]): A list of endpoint names corresponding to the vector stores.
+        vector_stores (list[VectorStore]): A list of `VectorStore` objects, each responsible for handling embedding and search operations for a specific endpoint.
+        endpoint_names (list[str]): A list of endpoint names corresponding to the `vector_stores`.
 
     Returns:
         FastAPI: Server with intialized search endpoints
@@ -123,12 +123,16 @@ def get_server(vector_stores: list[VectorStore], endpoint_names: list[str]) -> F
 
 
 def run_server(vector_stores: list[VectorStore], endpoint_names: list[str], port: int = 8000):
-    """Create and run a FastAPI server with search endpoints.
+    """Create and run a `FastAPI` server with search endpoints.
 
     Args:
-        vector_stores (list[VectorStore]): A list of vector store objects, each responsible for handling embedding and search operations for a specific endpoint.
-        endpoint_names (list[str]): A list of endpoint names corresponding to the vector stores.
+        vector_stores (list[VectorStore]): A list of `VectorStore` objects, each responsible for handling embedding and search operations for a specific endpoint.
+        endpoint_names (list[str]): A list of endpoint names corresponding to the `vector_stores`.
         port (int): [optional] The port on which the API server will run. Defaults to 8000.
+
+    Raises:
+        DataValidationError: Raised if the input port is out of bounds.
+
     """
     logging.info("Starting ClassifAI API")
 
@@ -147,7 +151,7 @@ def make_endpoints(router: APIRouter | FastAPI, vector_stores_dict: dict[str, Ve
     """Create and register the different endpoints to your app.
 
     Args:
-        router (APIRouter | FastAPI): The FastAPI application instance.
+        router (APIRouter | FastAPI): The FastAPI application or router instance.
         vector_stores_dict (dict[str, VectorStore]): The name of the endpoint to be created.
     """
     for endpoint_name, vector_store in vector_stores_dict.items():
@@ -161,7 +165,7 @@ def _create_embedding_endpoint(router: APIRouter | FastAPI, endpoint_name: str,
     """Create and register an embedding endpoint for a specific vector store.
 
     Args:
-        router (APIRouter | FastAPI): The FastAPI application instance.
+        router (APIRouter | FastAPI): The `FastAPI` application instance.
         endpoint_name (str): The name of the endpoint to be created.
         vector_store: The vector store object responsible for generating embeddings.
 
@@ -196,7 +200,7 @@ def _create_search_endpoint(router: APIRouter | FastAPI, endpoint_name: str, vec
     Args:
         router (APIRouter | FastAPI): The FastAPI application instance.
         endpoint_name (str): The name of the endpoint to be created.
-        vector_store: The vector store object responsible for performing search operations.
+        vector_store: The `VectorStore` object responsible for performing search operations.
 
     The created endpoint accepts POST requests with input data and a query parameter
     specifying the number of results to return. It performs a search operation using
@@ -233,7 +237,7 @@ def _create_reverse_search_endpoint(router: APIRouter | FastAPI, endpoint_name:
     """Create and register a reverse_search endpoint for a specific vector store.
 
     Args:
-        router (APIRouter | FastAPI): The FastAPI application instance.
+        router (APIRouter | FastAPI): The `FastAPI` application instance.
         endpoint_name (str): The name of the endpoint to be created.
         vector_store: The vector store object responsible for performing search operations.