Fix API doc build (#556)

* Error on doc build warnings

* Add missing maxdepth parameter value

* Restore docs build steps which installed jupytergis wheels

Unclear why removed in #412

* Remove pip install from build_packages.py

Setting up the environment should probably be decoupled from the build
helper script.

* Try build _then_ build:packages

This actually worked locally 🙏

* Fix type annotation errors

* Fix docutils warning

```
/home/docs/micromamba/envs/jupytergis-docs/lib/python3.12/site-packages/jupytergis_lab/notebook/gis_document.py:docstring of jupytergis_lab.notebook.gis_document.GISDocument:5: WARNING: Field list ends without a blank line; unexpected unindent. [docutils]
```

* Remove undefined `_type_` type

* Fix some broken type documentation

* Bugfix: Remove mutable default arguments

Author: mfisher87

.readthedocs.yaml

@@ -37,10 +37,17 @@ build:
     pre_build:
       - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm install"
       - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm build"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm build:packages"
+      - |-
+        /bin/bash --login -c "micromamba run -n jupytergis-docs \
+          python -m pip install \
+          $(ls ./python/jupytergis_core/dist/jupytergis*.whl) \
+          $(ls ./python/jupytergis_lab/dist/jupytergis*.whl) \
+          $(ls ./python/jupytergis_qgis/dist/jupytergis*.whl)"
 
     build:
       html:
         - |-
           /bin/bash --login -c "cd docs && micromamba run -n jupytergis-docs \
-          python -m sphinx -T -b html -d _build/doctrees -D language=en . \
+          python -m sphinx --fail-on-warning --keep-going --nitpicky --show-traceback --builder html --doctree-dir _build/doctrees --define language=en . \
           $READTHEDOCS_OUTPUT/html"

docs/user_guide/features/index.md

@@ -1,7 +1,7 @@
 # Features
 
 ```{toctree}
-:maxdepth:
+:maxdepth: 2
 
 extension.rst
 collab.rst

pyproject.toml

@@ -44,5 +44,7 @@ extend-include = ["*.ipynb"]
 select = [
     # pycodestyle
     "E",
+    # bugbear: Disallow mutable argument defaults
+    "B006",
 ]
 ignore = ["E501", "E731"]

python/jupytergis_lab/jupytergis_lab/notebook/gis_document.py

@@ -43,8 +43,7 @@ class GISDocument(CommWidget):
     """
     Create a new GISDocument object.
 
-    :param path: the path to the file that you would like to open.
-    If not provided, a new empty document will be created.
+    :param path: the path to the file that you would like to open. If not provided, a new empty document will be created.
     """
 
     def __init__(
@@ -234,7 +233,7 @@ def add_geojson_layer(
         logical_op: str | None = None,
         feature: str | None = None,
         operator: str | None = None,
-        value: Union[str, number, float] | None = None,
+        value: Union[str, int, float] | None = None,
         color_expr=None,
     ):
         """
@@ -244,7 +243,6 @@ def add_geojson_layer(
         :param path: The path to the JSON file to embed into the jGIS file.
         :param data: The raw GeoJSON data to embed into the jGIS file.
         :param type: The type of the vector layer to create.
-        :param color: The color to apply to features.
         :param opacity: The opacity, between 0 and 1.
         :param color_expr: The style expression used to style the layer, defaults to None
         """
@@ -334,9 +332,9 @@ def add_image_layer(
 
     def add_video_layer(
         self,
-        urls: [],
+        urls: List,
         name: str = "Image Layer",
-        coordinates: [] = [],
+        coordinates: Optional[List] = None,
         opacity: float = 1,
     ):
         """
@@ -347,6 +345,8 @@ def add_video_layer(
         :param coordinates: Corners of video specified in longitude, latitude pairs.
         :param opacity: The opacity, between 0 and 1.
         """
+        if coordinates is None:
+            coordinates = []
 
         if urls is None or coordinates is None:
             raise ValueError("URLs and Coordinates are required")
@@ -383,14 +383,14 @@ def add_tiff_layer(
         """
         Add a tiff layer
 
-        :param str url: URL of the tif
-        :param int min: Minimum pixel value to be displayed, defaults to letting the map display set the value
-        :param int max: Maximum pixel value to be displayed, defaults to letting the map display set the value
-        :param str name: The name that will be used for the object in the document, defaults to "Tiff Layer"
-        :param bool normalize: Select whether to normalize values between 0..1, if false than min/max have no effect, defaults to True
-        :param bool wrapX: Render tiles beyond the tile grid extent, defaults to False
-        :param float opacity: The opacity, between 0 and 1, defaults to 1.0
-        :param _type_ color_expr: The style expression used to style the layer, defaults to None
+        :param url: URL of the tif
+        :param min: Minimum pixel value to be displayed, defaults to letting the map display set the value
+        :param max: Maximum pixel value to be displayed, defaults to letting the map display set the value
+        :param name: The name that will be used for the object in the document, defaults to "Tiff Layer"
+        :param normalize: Select whether to normalize values between 0..1, if false than min/max have no effect, defaults to True
+        :param wrapX: Render tiles beyond the tile grid extent, defaults to False
+        :param opacity: The opacity, between 0 and 1, defaults to 1.0
+        :param color_expr: The style expression used to style the layer, defaults to None
         """
 
         source = {
@@ -421,7 +421,7 @@ def add_hillshade_layer(
         self,
         url: str,
         name: str = "Hillshade Layer",
-        urlParameters: Dict = {},
+        urlParameters: Optional[Dict] = None,
         attribution: str = "",
     ):
         """
@@ -431,6 +431,8 @@ def add_hillshade_layer(
         :param str name: The name that will be used for the object in the document, defaults to "Hillshade Layer"
         :param attribution: The attribution.
         """
+        if urlParameters is None:
+            urlParameters = {}
 
         source = {
             "type": SourceType.RasterDemSource,
@@ -454,14 +456,14 @@ def add_hillshade_layer(
 
     def add_heatmap_layer(
         self,
-        feature: string,
+        feature: str,
         path: str | Path | None = None,
         data: Dict | None = None,
         name: str = "Heatmap Layer",
         opacity: float = 1,
-        blur: number = 15,
-        radius: number = 8,
-        gradient: List[str] = ["#00f", "#0ff", "#0f0", "#ff0", "#f00"],
+        blur: int = 15,
+        radius: int = 8,
+        gradient: Optional[List[str]] = None,
     ):
         """
         Add a Heatmap Layer to the document.
@@ -495,6 +497,9 @@ def add_heatmap_layer(
         if data is not None:
             parameters = {"data": data}
 
+        if gradient is None:
+            gradient = ["#00f", "#0ff", "#0f0", "#ff0", "#f00"]
+
         source = {
             "type": SourceType.GeoJSONSource,
             "name": f"{name} Source",
@@ -609,16 +614,16 @@ def add_filter(
         logical_op: str,
         feature: str,
         operator: str,
-        value: Union[str, number, float],
+        value: Union[str, int, float],
     ):
         """
         Add a filter to a layer
 
-        :param str layer_id: The ID of the layer to filter
-        :param str logical_op: The logical combination to apply to filters. Must be "any" or "all"
-        :param str feature: The feature to be filtered on
-        :param str operator: The operator used to compare the feature and value
-        :param Union[str, number, float] value: The value to be filtered on
+        :param layer_id: The ID of the layer to filter
+        :param logical_op: The logical combination to apply to filters. Must be "any" or "all"
+        :param feature: The feature to be filtered on
+        :param operator: The operator used to compare the feature and value
+        :param value: The value to be filtered on
         """
         layer = self._layers.get(layer_id)
 
@@ -655,16 +660,16 @@ def update_filter(
         logical_op: str,
         feature: str,
         operator: str,
-        value: Union[str, number, float],
+        value: Union[str, int, float],
     ):
         """
         Update a filter applied to a layer
 
-        :param str layer_id: The ID of the layer to filter
-        :param str logical_op: The logical combination to apply to filters. Must be "any" or "all"
-        :param str feature: The feature to update the value for
-        :param str operator: The operator used to compare the feature and value
-        :param Union[str, number, float] value: The new value to be filtered on
+        :param layer_id: The ID of the layer to filter
+        :param logical_op: The logical combination to apply to filters. Must be "any" or "all"
+        :param feature: The feature to update the value for
+        :param operator: The operator used to compare the feature and value
+        :param value: The new value to be filtered on
         """
         layer = self._layers.get(layer_id)
 

scripts/build_packages.py

@@ -1,3 +1,8 @@
+"""Build all JupyterGIS packages.
+
+IMPORTANT: Requires dependencies in requirements-build.txt
+"""
+
 import subprocess
 from pathlib import Path
 
@@ -8,8 +13,6 @@ def execute(cmd: str, cwd=None):
 
 def build_packages():
     root_path = Path(__file__).parents[1]
-    requirements_build_path = root_path / "requirements-build.txt"
-    install_build_deps = f"python -m pip install -r {requirements_build_path}"
 
     python_package_prefix = "python"
     python_packages = [
@@ -20,8 +23,6 @@ def build_packages():
         "jupytergis_lite",
     ]
 
-    execute(install_build_deps)
-
     for py_package in python_packages:
         execute("hatch build", cwd=root_path / python_package_prefix / py_package)