docs: docstrings and mkdocs md files for three modules

call_models/obs_map.py

@@ -62,7 +62,21 @@ _colors = [
 
 whale2color = {k: v for k, v in zip(sw_wv.WHALE_CLASSES, _colors)}
 
-def create_map(tile_name:str, location:Tuple, zoom_start: int = 7):
+def create_map(tile_name:str, location:Tuple[float], zoom_start: int = 7) -> folium.Map:
+    """
+    Create a folium map with the specified tile layer
+
+    Parameters:
+        tile_name (str): The name of the tile layer to use. Options include:
+                        'Open Street Map', 'Esri Ocean', 'Esri Images', 
+                        'Stamen Toner', 'Stamen Watercolor', 
+                        'CartoDB Positron', 'CartoDB Dark_Matter'.
+        location (Tuple): Coordinates (lat, lon) of the map center, as floats.
+        zoom_start (int, optional): The initial zoom level for the map. Default is 7.
+
+    Returns:
+        folium.Map: A folium Map object with the specified settings.
+    """
     # https://xyzservices.readthedocs.io/en/stable/gallery.html 
     # get teh attribtuions from here once we pick the 2-3-4 options 
     # make esri ocean the default
@@ -103,12 +117,27 @@ def create_map(tile_name:str, location:Tuple, zoom_start: int = 7):
 
 def present_obs_map(dataset_id:str = "Saving-Willy/Happywhale-kaggle",
                     data_files:str = "data/train-00000-of-00001.parquet", 
-                    dbg_show_extra:bool = False):
-    '''
-    render a map, with a selectable tileset, and show markers for each of the whale 
-    observations
+                    dbg_show_extra:bool = False) -> dict:
+    """
+    Render map plus tile selector, with markers for whale observations
     
-    '''
+
+    This function loads whale observation data from a specified dataset and
+    file, creates a pandas DataFrame compliant with Folium/Streamlit maps, and
+    renders an interactive map with markers for each observation.  The map
+    allows users to select a tileset, and displays markers with species-specific
+    colors.
+
+    Args:
+        dataset_id (str): The ID of the dataset to load from Hugging Face. Default is "Saving-Willy/Happywhale-kaggle".
+        data_files (str): The path to the data file to load. Default is "data/train-00000-of-00001.parquet".
+        dbg_show_extra (bool): If True, add a few extra sample markers for visualization. Default is False.
+
+    Returns:
+        dict: Selected data from the Folium/leaflet.js interactions in the browser.
+
+    """
+
     # load/download data from huggingface dataset
     metadata = load_dataset(dataset_id, data_files=data_files)
     

call_models/whale_gallery.py

@@ -3,17 +3,22 @@ import streamlit as st
 
 import whale_viewer as sw_wv
 
-def render_whale_gallery(n_cols:int = 4):
+
+def render_whale_gallery(n_cols:int = 4) -> None:
     """
     Renders a gallery of whale images + urls in a grid format using Streamlit.
 
+    The function formats whale names, creates a grid layout for images, and
+    applies custom CSS styles Each image is displayed with a caption and a link
+    to a reference URL.
+
+
     Parameters:
-    n_cols (int): Number of columns in the grid. Default is 4.
+        n_cols (int): Number of columns in the grid. Default is 4.
 
-    The function formats whale names, creates a grid layout for images, and applies custom CSS styles
-    Each image is displayed with a caption and a link to a reference URL.
     """
-    def format_whale_name(name):
+    def _format_whale_name(name:str) -> str:
+        '''clean up the whale name for display'''
         return name.replace("_", " ").capitalize()
     
     # make a grid of images, use some css to get more uniform
@@ -58,7 +63,7 @@ def render_whale_gallery(n_cols:int = 4):
     cols = cycle(st.columns(n_cols)) 
     for ix in range(len(sw_wv.df_whale_img_ref)):
         img_name = sw_wv.df_whale_img_ref.iloc[ix].loc["WHALE_IMAGES"]
-        whale_name = format_whale_name(str(sw_wv.df_whale_img_ref.iloc[ix].name))
+        whale_name = _format_whale_name(str(sw_wv.df_whale_img_ref.iloc[ix].name))
         url = sw_wv.df_whale_img_ref.iloc[ix].loc['WHALE_REFERENCES']
         image_path = f"images/references/{img_name}"
         #next(cols).image(image_path, width=150, caption=f"{whale_name}")
@@ -91,5 +96,4 @@ if __name__ == "__main__":
     tg_cont = st.container(key="swgallery")
     with tg_cont:
         render_whale_gallery(n_cols=4)
-    
-    pass
+    

call_models/whale_viewer.py

@@ -104,8 +104,8 @@ df_whale_img_ref = pd.DataFrame(
 
 def format_whale_name(whale_class:str) -> str:
     """
-    Formats a whale class name by replacing underscores with spaces and capitalizing each word.
-
+    Formats a whale class name for display 
+    
     Args:
         whale_class (str): The class name of the whale, with words separated by underscores.
 
@@ -125,7 +125,8 @@ def display_whale(whale_classes:List[str], i:int, viewcontainer=None):
         i (int): The index of the whale class to display.
         viewcontainer: The container to display the whale information. If 
             not provided, use the current streamlit context (works via 
-            'with <container>' syntax)
+            'with `container`' syntax)
+
     Returns:
         None
     

docs/obs_map.md

@@ -1,2 +1,7 @@
+This module provides rendering of observations on an interactive map, with a variety of tilesets available. 
+
+Note: OSM, ESRI, and CartoDB map tiles are served without authentication/tokens,
+and so render correctly on the huggingface deployment. The Stamen tiles render
+on localhost but require a token to present on a 3rd-party site.
 
 ::: call_models.obs_map

docs/whale_gallery.md

@@ -1,2 +1,4 @@
+This module provides a gallery of the whales and dolphins that the classifier 
+is trained on. It diplays the images and links to further info on the species.
 
-::: call_models.whale_gallery
+::: call_models.whale_gallery

docs/whale_viewer.md

@@ -1,2 +1,4 @@
+This module provides a streamlit rendering for the whales and dolphins that the classifier is aware of, and also holds the 
+metadata for them (images, class names that the classifier uses, and URLS for further information about each species).
 
 ::: call_models.whale_viewer

mkdocs.yaml

@@ -25,9 +25,9 @@ nav:
   - API:
     - Main app: main.md
     - Data entry handling: input_handling.md
+    - Map of observations: obs_map.md
     - Whale gallery: whale_gallery.md
     - Whale viewer: whale_viewer.md
-    - Map of observations: obs_map.md
     - Logging: st_logs.md
     - Tab-rendering fix (js): fix_tabrender.md