Update docs

Author: Stefan Kuethe

docs/api/basemaps.md

@@ -1,3 +1,5 @@
 # Basemaps
 
-::: openlayers.basemaps.BasemapLayer
+::: openlayers.basemaps.BasemapLayer
+
+::: openlayers.basemaps.Carto

docs/api/controls.md

@@ -1 +1,3 @@
 # Controls
+
+::: openlayers.controls

docs/examples/concepts/layers.py

@@ -2,7 +2,7 @@
 
 data = "https://openlayers.org/en/latest/examples/data/geojson/roads-seoul.geojson"
 
-geojson_layer = ol.VectorLayer(
+vector = ol.VectorLayer(
     id="roads",
     source=ol.VectorSource(url=data),
     fit_bounds=True,
@@ -11,6 +11,6 @@
 
 m = ol.Map(
     ol.View(rotation=3.14 / 8),
-    layers=[ol.BasemapLayer.carto(), geojson_layer]
+    layers=[ol.BasemapLayer.carto(), vector]
 )
 m.add_default_tooltip()

docs/examples/concepts/sources.py

@@ -1,14 +1,14 @@
 import openlayers as ol
 
-geojson_source = ol.VectorSource(
+geojson = ol.VectorSource(
     url="https://openlayers.org/en/latest/examples/data/geojson/roads-seoul.geojson"
 )
 
-geotiff_source = ol.GeoTIFFSource(
+geotiff = ol.GeoTIFFSource(
     sources=[{"url": "https://s2downloads.eox.at/demo/EOxCloudless/2020/rgbnir/s2cloudless2020-16bits_sinlge-file_z0-4.tif"}]
 )
 
-pmtiles_source = ol.PMTilesVectorSource(
+pmtiles = ol.PMTilesVectorSource(
     url="https://r2-public.protomaps.com/protomaps-sample-datasets/nz-buildings-v3.pmtiles",
     attributions=["© Land Information New Zealand"]
 )

docs/index.md

@@ -3,3 +3,16 @@
 ```python
 -8<-- "concepts/basic_map.py"
 ```
+
+Use the `Map` class if you just want to create an HTML document and the `MapWidget` class for an interactive
+widget in _Marimo_ or _Jupyter_ notebooks:
+
+```python
+# Widget
+m = ol.MapWidget(controls=[ol.ZoomSliderControl()])
+m
+
+# Standalone
+m = Map(controls=[ol.ZoomSliderControl()])
+m.save()
+```

mkdocs.yml

@@ -47,5 +47,5 @@ nav:
       - Styles: api/styles.md
       - Basemaps: api/basemaps.md
       - GeoPandas: api/geopandas.md
-      - Express: api/express.md
+      # - Express: api/express.md
   - Changelog: changelog.md

src/openlayers/basemaps.py

@@ -21,6 +21,8 @@
 
 
 class Carto(Enum):
+    """CartoDB basemap styles"""
+
     LIGHT_ALL = "light_all"
     DARK_ALL = "dark_all"
     VOYAGER_NO_LABLES = "rastertiles/voyager_nolabels"
@@ -59,12 +61,37 @@ def model(self) -> TileLayer:
 
     @staticmethod
     def osm() -> TileLayer:
+        """Create a OSM tile layer object
+
+        Returns:
+            An OSM raster tile layer
+
+        Examples:
+            >>> from openlayers.basemaps import BasemapLayer
+            >>> osm = BasemapLayer.osm()
+        """
         return TileLayer(id="osm", source=OSM())
 
     @staticmethod
     def carto(
         style_name: str | Carto = Carto.DARK_ALL, double_resolution: bool = True
     ) -> TileLayer:
+        """Create a CartoDB tile layer object
+
+        Note:
+            See [CartoDB/basemap-styles](https://github.com/CartoDB/basemap-styles) for available styles.
+
+        Args:
+            style_name (str | Carto): The name of the style
+            double_resolution (bool): Whether to use double resolution tiles
+
+        Returns:
+            A CartoDB raster tile layer
+
+        Examples:
+            >>> from openlayers.basemaps import BasemapLayer
+            >>> carto = BasemapLayer.carto()
+        """
         style = CartoRasterStyle(style=style_name, double_resolution=double_resolution)
         return TileLayer(
             id=f"carto-{Carto(style_name).value.replace('_', '-').replace('/', '-')}",

src/openlayers/controls.py

@@ -22,6 +22,9 @@
     "OverviewMapControl",
     "ScaleLineControl",
     "ZoomSliderControl",
+    "ZoomToExtentControl",
+    "ZoomControl",
+    "RotateControl",
     "MousePositionControl",
     "MapTilerGeocodingControl",
     "DrawControl",