Add docstrings

stfnkth · stfnkth · commit b562e116fd34 · 2025-05-06T00:29:43.000+02:00
diff --git a/docs/api/basemaps.md b/docs/api/basemaps.md
diff --git a/docs/api/controls.md b/docs/api/controls.md
@@ -0,0 +1,3 @@
+# Controls
+
+::: openlayers.controls
diff --git a/docs/api/express.md b/docs/api/express.md
@@ -0,0 +1,3 @@
+# OpenLayersExpress
+
+::: openlayers.express.GeoJSONLayer
diff --git a/docs/api/geopandas.md b/docs/api/geopandas.md
@@ -0,0 +1,5 @@
+# GeoPandas
+
+::: openlayers.geopandas.OLAccessor
+
+::: openlayers.geopandas.GeoDataFrame
diff --git a/docs/api/layers.md b/docs/api/layers.md
@@ -0,0 +1,4 @@
+# Layers
+
+::: openlayers.models.layers
+
diff --git a/docs/api/map.md b/docs/api/map.md
@@ -0,0 +1,5 @@
+# Map
+
+::: openlayers.map.Map
+
+::: openlayers.anywidget.MapWidget
diff --git a/docs/api/styles.md b/docs/api/styles.md
@@ -0,0 +1,3 @@
+# Styles
+
+::: openlayers.styles.FlatStyle
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,4 +34,12 @@ markdown_extensions:
 nav:
   - Get started: index.md
   # - Concepts: concept.md
+  - API documentation:
+      - Map: api/map.md
+      - Controls: api/controls.md
+      - Layers: api/layers.md
+      - Styles: api/styles.md
+      - Basemaps: api/basemaps.md
+      - GeoPandas: api/geopandas.md
+      - Express: api/express.md
   - Changelog: changelog.md
diff --git a/src/openlayers/__future__/__init__.py b/src/openlayers/__future__/__init__.py
diff --git a/src/openlayers/express.py b/src/openlayers/express.py
@@ -9,6 +9,17 @@
 
 
 class GeoJSONLayer(LayerLike):
+    """Initialize a new `GeoJSONLayer` instance
+
+    Args:
+        data (str | dict): Either an URL to a GeoJSON object
+            or a dictionary representing a GeoJSON object
+        id (str): The ID of the layer. If `None`, a random ID is generated
+        style (FlatStyle): The style to be applied to the layer. If `None` a default style is used
+        **kwargs (Any): Style arguments that are appended to the `Style` object.
+            Latter ones overwrite existing entries
+    """
+
     def __init__(
         self,
         data: str | dict,
@@ -35,6 +46,14 @@ def model(self) -> WebGLVectorLayer | VectorLayer:
     def to_map(
         self, lon: float = 0, lat: float = 0, zoom: float | int = 0, **kwargs
     ) -> Map:
+        """Initialize a new `Map` instance and add the layer to it
+
+        Args:
+            lon (float): The longitude of the initial view state of the map
+            lat (float): The latitude of the initial view state of the map
+            zoom (float | int): The initial zoom level of the map
+            **kwargs (Any): Arguments that are handed over to the `Map` instance
+        """
         m = Map(View(center=(lon, lat), zoom=zoom), **kwargs)
         m.add_layer(self)
         return m
diff --git a/src/openlayers/geopandas.py b/src/openlayers/geopandas.py
@@ -27,11 +27,23 @@ def gdf_to_geojson(data: gpd.GeoDataFrame, crs: str | None = Projection.WEB_MERC
 
 @pd.api.extensions.register_dataframe_accessor("ol")
 class OLAccessor:
+    """Create a new `OLAccessor` instance
+
+    Args:
+        gdf (gpd.GeoDataFrame): The `GeoDataFrame`,
+            to which the `openlayers` extension is added
+    """
+
     def __init__(self, gdf: gpd.GeoDataFrame) -> None:
         self._gdf = gdf
         self._default_style = default_style()
 
     def to_source(self) -> VectorSource:
+        """Return data frame as OL vector source
+
+        Returns:
+            An OL vector source
+        """
         feature_collection = gdf_to_geojson(self._gdf)
         source = VectorSource(geojson=feature_collection)
         return source
@@ -43,6 +55,11 @@ def to_layer(
         webgl: bool = True,
         **kwargs,
     ) -> VectorLayer | WebGLVectorLayer:
+        """Return data frame as OL vector layer
+
+        Returns:
+            An OL vector layer
+        """
         style = style or self._default_style
         layer_class = WebGLVectorLayer if webgl else VectorLayer
         layer = layer_class(id=layer_id, style=style, source=self.to_source(), **kwargs)
@@ -57,6 +74,19 @@ def explore(
         webgl: bool = True,
         **kwargs,
     ) -> MapWidget:
+        """Create a vector layer and add it to a new `Map` instance
+
+        Args:
+            style (FlatStyle | dict): The style applied to the layer.
+                If `None`, a default style is used
+            tooltip (bool | str): Whether a tooltip should be added to the map.
+                Either `True` to add a default tooltip,
+                or a mustache template string to add a custom tooltip
+            controls (list[ControlT | dict]): Controls initially added to the map
+            layer_id (str): The ID of the layer
+            webgl (bool): Whether the layer should be added to the map
+                as `WebGLVectorLayer` or as `VectorLayer`
+        """
         layer = self.to_layer(style=style, layer_id=layer_id, webgl=webgl)
 
         m = MapWidget(controls=controls, **kwargs)
diff --git a/src/openlayers/map.py b/src/openlayers/map.py
@@ -15,7 +15,7 @@
 
 
 class Map(object):
-    """Initialize a `Map` instance
+    """Initialize a new `Map` instance
 
     Args:
         view (View): The initial view state of the map
@@ -70,7 +70,7 @@ def remove_layer(self, layer_id: str) -> None:
         """Remove a layer from the map
 
         Args:
-            layer_id (str): The Id of the layer to be removed
+            layer_id (str): The ID of the layer to be removed
         """
         self.add_call("removeLayer", layer_id)
 
@@ -89,7 +89,7 @@ def remove_control(self, control_id: str) -> None:
         """Remove a control from the map
 
         Args:
-            control_id (str): The Id of the control to be removed
+            control_id (str): The ID of the control to be removed
         """
         self.add_call("removeControl", control_id)
 
@@ -114,26 +114,26 @@ def set_opacity(self, layer_id: str, opacity: float = 1) -> None:
         """Set the opacity of a layer
 
         Args:
-            layer_id (str): The Id of the layer
+            layer_id (str): The ID of the layer
             opacity (float): The opacity of the layer. A value between 0 and 1
         """
         self.add_layer_call(layer_id, "setOpacity", opacity)
 
     def set_visibility(self, layer_id: str, visible: bool = False) -> None:
-        """Set the visibility of the layer
+        """Set the visibility of a layer
 
         Args:
-            layer_id (str): The Id of the layer
+            layer_id (str): The ID of the layer
             visible (bool): Whether the layer is visible or not
         """
         self.add_layer_call(layer_id, "setVisible", visible)
 
-    def set_style(self, layer_id: str, style: dict | FlatStyle) -> None:
+    def set_style(self, layer_id: str, style: FlatStyle | dict) -> None:
         """Set the style of a layer
 
         Args:
-            layer_id (str): The Id of the layer
-            style (dict | FlatStyle): The style of the layer
+            layer_id (str): The ID of the layer
+            style (FlatStyle | dict): The style of the layer
         """
         if isinstance(style, FlatStyle):
             style = style.model_dump()
@@ -146,10 +146,10 @@ def to_html(self, **kwargs) -> str:
         return HTMLTemplate().render(data=data, **kwargs)
 
     def save(self, path: Path | str = None, preview: bool = True, **kwargs) -> str:
-        """Save map as HTML document
+        """Save map as an HTML document
 
         Args:
-            path (path | str): The Path to the output file. If `None`, a temporary file is created
+            path (Path | str): The Path to the output file. If `None`, a temporary file is created
             preview (bool): Whether the file should be opened in your default browser after saving
         """
         path = write_file(content=self.to_html(**kwargs), path=path)
diff --git a/src/openlayers/models/__init__.py b/src/openlayers/models/__init__.py
diff --git a/src/openlayers/styles.py b/src/openlayers/styles.py
@@ -10,6 +10,13 @@ def fix_keys(d: dict) -> dict:
 # TODO: Move to models folder
 # See https://openlayers.org/en/latest/apidoc/module-ol_style_flat.html
 class FlatStyle(BaseModel):
+    """Flat style
+
+    Note:
+        See [ol-apidoc/module-ol_style_flat](https://openlayers.org/en/latest/apidoc/module-ol_style_flat.html)
+        for all available style parameters.
+    """
+
     model_config = ConfigDict(extra="allow")
 
     fill_color: str | list | None = None

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Controls`
	`2`	`+`
	`3`	`+::: openlayers.controls`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# OpenLayersExpress`
	`2`	`+`
	`3`	`+::: openlayers.express.GeoJSONLayer`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# Layers
++
 +::: openlayers.models.layers
++
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Styles`
	`2`	`+`
	`3`	`+::: openlayers.styles.FlatStyle`