unify docstring for endpoints

Author: ix-56h

src/server/main.py

@@ -61,59 +61,100 @@ async def health_check() -> dict[str, str]:
 async def head_root() -> HTMLResponse:
     """Respond to HTTP HEAD requests for the root URL.
 
-    Mirrors the headers and status code of the index page.
+    **This endpoint mirrors the headers and status code of the index page**
+    for HTTP HEAD requests, providing a lightweight way to check if the server
+    is responding without downloading the full page content.
 
-    Returns
-    -------
-    HTMLResponse
-        An empty HTML response with appropriate headers.
+    **Returns**
+
+    - **HTMLResponse**: An empty HTML response with appropriate headers
 
     """
     return HTMLResponse(content=None, headers={"content-type": "text/html; charset=utf-8"})
 
 
 @app.get("/robots.txt", include_in_schema=False)
 async def robots() -> FileResponse:
-    """Serve the ``robots.txt`` file to guide search engine crawlers.
+    """Serve the robots.txt file to guide search engine crawlers.
 
-    Returns
-    -------
-    FileResponse
-        The ``robots.txt`` file located in the static directory.
+    **This endpoint serves the ``robots.txt`` file located in the static directory**
+    to provide instructions to search engine crawlers about which parts of the site
+    they should or should not index.
+
+    **Returns**
+
+    - **FileResponse**: The ``robots.txt`` file located in the static directory
 
     """
     return FileResponse("static/robots.txt")
 
 
 @app.get("/llm.txt")
 async def llm_txt() -> FileResponse:
-    """Serve the ``llm.txt`` file to provide information about the site to LLMs.
+    """Serve the llm.txt file to provide information about the site to LLMs.
+
+    **This endpoint serves the ``llm.txt`` file located in the static directory**
+    to provide information about the site to Large Language Models (LLMs)
+    and other AI systems that may be crawling the site.
+
+    **Returns**
 
-    Returns
-    -------
-    FileResponse
-        The ``llm.txt`` file located in the static directory.
+    - **FileResponse**: The ``llm.txt`` file located in the static directory
 
     """
     return FileResponse("static/llm.txt")
 
 
 @app.get("/docs", response_class=HTMLResponse, include_in_schema=False)
 async def custom_swagger_ui(request: Request) -> HTMLResponse:
-    """Swagger UI documentation."""
+    """Serve custom Swagger UI documentation.
+
+    **This endpoint serves a custom Swagger UI interface**
+    for the API documentation, providing an interactive way to explore
+    and test the available endpoints.
+
+    **Parameters**
+
+    - **request** (`Request`): The incoming HTTP request
+
+    **Returns**
+
+    - **HTMLResponse**: Custom Swagger UI documentation page
+
+    """
     return templates.TemplateResponse("swagger_ui.jinja", {"request": request})
 
 
 @app.get("/api", include_in_schema=True)
 def openapi_json_get() -> JSONResponse:
-    """Return the OpenAPI schema (openapi.json)."""
+    """Return the OpenAPI schema.
+
+    **This endpoint returns the OpenAPI schema (openapi.json)**
+    that describes the API structure, endpoints, and data models
+    for documentation and client generation purposes.
+
+    **Returns**
+
+    - **JSONResponse**: The OpenAPI schema as JSON
+
+    """
     return JSONResponse(app.openapi())
 
 
 @app.api_route("/api", methods=["POST", "PUT", "DELETE", "OPTIONS", "HEAD"], include_in_schema=False)
 @app.api_route("/api/", methods=["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD"], include_in_schema=False)
 def openapi_json() -> JSONResponse:
-    """Return the OpenAPI schema (openapi.json)."""
+    """Return the OpenAPI schema for various HTTP methods.
+
+    **This endpoint returns the OpenAPI schema (openapi.json)**
+    for multiple HTTP methods, providing API documentation
+    for clients that may use different request methods.
+
+    **Returns**
+
+    - **JSONResponse**: The OpenAPI schema as JSON
+
+    """
     return JSONResponse(app.openapi())
 
 

src/server/routers/ingest.py

@@ -83,23 +83,24 @@ async def api_ingest_get(
 
 @router.get("/api/download/file/{ingest_id}", response_class=FileResponse)
 async def download_ingest(ingest_id: str) -> FileResponse:
-    """Return the first ``*.txt`` file produced for ``ingest_id`` as a download.
-
-    Parameters
-    ----------
-    ingest_id : str
-        Identifier that the ingest step emitted (also the directory name that stores the artefacts).
-
-    Returns
-    -------
-    FileResponse
-        Streamed response with media type ``text/plain`` that prompts the browser to download the file.
-
-    Raises
-    ------
-    HTTPException
-        **404** - digest directory is missing or contains no ``*.txt`` file.
-        **403** - the process lacks permission to read the directory or file.
+    """Download the first text file produced for an ingest ID.
+
+    **This endpoint retrieves the first ``*.txt`` file produced during the ingestion process**
+    and returns it as a downloadable file. The file is streamed with media type ``text/plain``
+    and prompts the browser to download it.
+
+    **Parameters**
+
+    - **ingest_id** (`str`): Identifier that the ingest step emitted
+
+    **Returns**
+
+    - **FileResponse**: Streamed response with media type ``text/plain``
+
+    **Raises**
+
+    - **HTTPException**: **404** - digest directory is missing or contains no ``*.txt`` file
+    - **HTTPException**: **403** - the process lacks permission to read the directory or file
 
     """
     directory = TMP_BASE_PATH / ingest_id