Enable pydocstyle (D) ruff rule and add more docs (#21)

* Use pydocstyle (D) rule with google convention

Add a ruff rule to catch missing documentation. Using google convention so that undocumented-param (D417) rule is enabled to catch missing params, xref https://docs.astral.sh/ruff/rules/undocumented-param. Extended to include D213 (instead of D212) and D410 rules too.

* Fix D100 Missing docstring in public module

* Fix D101 Missing docstring in public class

* Fix D103 Missing docstring in public function

Also ignore rule D205 to allow first sentence of docstring to wrap to multiple lines.

* Fix  D417 Missing argument description in the docstring

* Update indent in pyproject.toml file

tests/test_api.py

@@ -1,3 +1,5 @@
+"""Tests for chat API endpoint."""
+
 from uuid import uuid4
 
 import pytest
@@ -10,7 +12,7 @@ from geo_assistant.api.app import app
 
 @pytest_asyncio.fixture
 async def initialized_app():
-    """Initialize the app's chatbot before testing"""
+    """Initialize the app's chatbot before testing."""
     # Manually initialize the chatbot as the lifespan would
     app.state.chatbot = await create_graph()
     yield app
@@ -21,6 +23,7 @@ async def initialized_app():
 
 @pytest.mark.xfail
 async def test_call_api(initialized_app):
+    """Test calling the API at the /chat HTTP POST endpoint."""
     async with AsyncClient(
         transport=ASGITransport(app=initialized_app),
         base_url="http://test",

tests/tools/test_buffer.py

@@ -1,3 +1,5 @@
+"""Tests for buffer tool."""
+
 from geojson_pydantic import Feature, Point
 from langchain_core.tools.base import ToolCall
 from pytest import fixture
@@ -8,6 +10,7 @@ from geo_assistant.tools.buffer import get_search_area
 
 @fixture
 def geo_assistant_fixture():
+    """Fixture with a GeoJSON point feature in a GeoAssistantState."""
     place_geojson = Feature(
         type="Feature",
         geometry=Point(type="Point", coordinates=[-9.1393, 38.7223]),
@@ -22,6 +25,7 @@ def geo_assistant_fixture():
 
 
 async def test_get_search_area(geo_assistant_fixture):
+    """Ensure that `get_search_area` tool returns a buffer Polygon."""
     # Call the underlying function directly to test the logic
     # This bypasses the injection framework which is better suited for integration tests
     command = await get_search_area.ainvoke(

tests/tools/test_naip.py

@@ -1,3 +1,5 @@
+"""Tests for NAIP tool."""
+
 from types import NoneType
 
 import pytest
@@ -19,7 +21,6 @@ async def test_fetch_naip():
       - Internet access (to reach Planetary Computer STAC + blobs)
       - Planetary Computer / NAIP service to be up
     """
-
     # Union Market coordinates from GeoNames: 38.90789, -76.99831
     #   N 38°54'28"  W 76°59'54"
     # We'll use a small neighborhood AOI around that point.
@@ -60,7 +61,6 @@ async def test_fetch_naip_too_large():
       - Internet access (to reach Planetary Computer STAC + blobs)
       - Planetary Computer / NAIP service to be up
     """
-
     # Union Market coordinates from GeoNames: 38.90789, -76.99831
     #   N 38°54'28"  W 76°59'54"
     # We'll use a small neighborhood AOI around that point.

tests/tools/test_overture.py

@@ -1,3 +1,5 @@
+"""Tests for Overture tool."""
+
 import os
 
 import geopandas as gpd
@@ -57,6 +59,7 @@ def geo_assistant_with_buffer_fixture():
 
 
 async def test_get_place():
+    """Ensure that `get_place` tool returns an Overture place given a place_name."""
     command = await get_place.ainvoke(
         ToolCall(
             name="get_place",
@@ -69,6 +72,10 @@ async def test_get_place():
 
 
 async def test_get_places_within_buffer(geo_assistant_with_buffer_fixture):
+    """
+    Ensure that `get_places_within_buffer` tool returns multiple Overture places that
+    fit match the category 'cafe' within a specific buffer area around a location.
+    """
     command = await get_places_within_buffer.ainvoke(
         ToolCall(
             name="get_places_within_buffer",

tests/tools/test_summarize.py

@@ -23,6 +23,10 @@ TEST_IMAGE_URL = "https://petapixel.com/assets/uploads/2022/08/French-Officials-
     ],
 )
 async def test_summarize_sat_img(img_url, summary):
+    """
+    Ensure that the `summarize_sat_img` tool can describe a satellite image in JPEG
+    format.
+    """
     # Load the image from the supplied URL and encode it in base64
     headers = {
         "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",