docs(pydeck,pydeck-carto): Add documentation for pydeck v0.9 (#8853)

visgl · Apr 29, 2024 · a874dd0 · a874dd0
1 parent be76eef
commit a874dd0
Show file tree

Hide file tree

Showing 14 changed files with 405 additions and 162 deletions.
diff --git a/bindings/pydeck-carto/README.md b/bindings/pydeck-carto/README.md
@@ -34,13 +34,15 @@ carto_auth = CartoAuth.from_oauth()
 # Register new layer types in pydeck
 pdkc.register_layers()
 
-# Render CARTO layer in pydeck
+# Create CARTO data source
 data = pdkc.sources.vector_query_source(
     access_token=carto_auth.get_access_token(),
     api_base_url=carto_auth.get_api_base_url(),
     connection_name="carto_dw",
     sql_query="SELECT geom, name FROM carto-demo-data.demo_tables.world_airports",
 )
+
+# Render CARTO layer in pydeck
 layer = pdk.Layer(
     "VectorTileLayer",
     data=data,

diff --git a/bindings/pydeck-carto/docs/changelog.rst b/bindings/pydeck-carto/docs/changelog.rst
@@ -6,18 +6,22 @@ Releases and associated GitHub PRs for pydeck-carto are documented here.
 0.2 Releases
 ------------
 
-0.2.0b0 - Apr 24 2024
+0.2.0 - Apr 29 2024
 ^^^^^^^^^^^^^^^^^^^
 - Update to deck.gl v9.0
 - Rename register_carto_layer to register_layers
 - Add layer enums: VectorTileLayer, H3TileLayer, QuadbinTileLayer
 - Add source functions: vector_table_source, vector_query_source, vector_tileset_source, h3_table_source, h3_query_source, h3_tileset_source, quadbin_table_source, quadbin_query_source, quadbin_tileset_source
 
+0.2.0b0 - Apr 24 2024
+^^^^^^^^^^^^^^^^^^^^^
+- See v0.2.0 release
+
 0.1 Releases
 ------------
 
 0.1.1b0 - Apr 24 2024
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
 - Update to deck.gl v8.9
 
 0.1.0 - Nov 04 2022

diff --git a/bindings/pydeck-carto/docs/index.rst b/bindings/pydeck-carto/docs/index.rst
@@ -26,7 +26,8 @@ Index
    :maxdepth: 2
    :caption: API Reference
 
-   layer
+   layers
+   sources
    styles
 
 .. toctree::

diff --git a/bindings/pydeck-carto/docs/installation.rst b/bindings/pydeck-carto/docs/installation.rst
@@ -23,6 +23,9 @@ Via conda
 Using it on Jupyter notebook
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. WARNING::
+   Jupyter-specific features are not currently supported in pydeck v0.9+.
+
 In order to use the library in Jupyter notebook (or jupyter lab) requires that pydeck would be properly enabled
 
 Please follow the latest instructions to enable pydeck for Jupyter `here <https://pydeck.gl/installation.html#enabling-pydeck-for-jupyter>`_

diff --git a/bindings/pydeck-carto/docs/layer.rst b/bindings/pydeck-carto/docs/layer.rst
diff --git a/bindings/pydeck-carto/docs/layers.rst b/bindings/pydeck-carto/docs/layers.rst
@@ -0,0 +1,118 @@
+CARTO Layers
+============
+
+CARTO layers render cloud data from any connection (BigQuery, Snowflake, Redshift, Postgres, Databricks). Layer types pydeck-carto wrap the equivalent `layer types
+from deck.gl <https://deck.gl/docs/api-reference/carto/overview#carto-layers>`_.
+
+Pydeck-carto layers are not included in pydeck by default, so calling :meth:`pydeck_carto.register_layers` is required to register the CARTO layers with pydeck.
+
+Example
+^^^^^^^
+
+.. code-block:: python
+
+    import pydeck as pdk
+    import pydeck_carto as pdkc
+    from carto_auth import CartoAuth
+
+    # Authentication with CARTO
+    carto_auth = CartoAuth.from_oauth()
+
+    # Register CARTO layers in pydeck
+    pdkc.register_layers()
+
+    # Create CARTO data source
+    data = pdkc.sources.vector_query_source(
+        access_token=carto_auth.get_access_token(),
+        api_base_url=carto_auth.get_api_base_url(),
+        connection_name="carto_dw",
+        sql_query="SELECT geom, name FROM carto-demo-data.demo_tables.world_airports",
+    )
+
+    # Render CARTO layer in pydeck
+    layer = pdk.Layer(
+        "VectorTileLayer",
+        data=data,
+        get_fill_color=[238, 77, 90],
+        point_radius_min_pixels=2.5,
+        pickable=True,
+    )
+
+    view_state = pdk.ViewState(latitude=0, longitude=0, zoom=1)
+    tooltip={"html": "<b>Name:</b> {name}", "style": {"color": "white"}}
+    pdk.Deck(layer, map_style=pdk.map_styles.ROAD, initial_view_state=view_state, tooltip=tooltip)
+
+.. figure:: images/layer-table.png
+
+.. code-block:: python
+
+    # SQL query from a BigQuery connection
+    data = pdkc.sources.vector_query_source(
+        access_token=carto_auth.get_access_token(),
+        api_base_url=carto_auth.get_api_base_url(),
+        connection_name="carto_dw",
+        sql_query="""
+            SELECT a.geom, a.name
+            FROM `carto-demo-data.demo_tables.world_airports` AS a,
+                 `carto-do-public-data.natural_earth.geography_glo_admin0countries_410` AS g
+            WHERE g.ADMIN = 'Spain' AND
+                  ST_INTERSECTS(a.geom, g.geom)
+        """,
+    )
+
+    # Render CARTO layer in pydeck
+    layer = pdk.Layer(
+        "VectorTileLayer",
+        data=data,
+        get_fill_color=[238, 77, 90],
+        point_radius_min_pixels=2.5,
+        pickable=True,
+    )
+
+    view_state = pdk.ViewState(latitude=36, longitude=-7.44, zoom=4)
+    tooltip = {"html": "<b>Name:</b> {name}", "style": {"color": "white"}}
+    pdk.Deck(layer, map_style=pdk.map_styles.ROAD, initial_view_state=view_state, tooltip=tooltip)
+
+.. figure:: images/layer-query.png
+
+Error management
+^^^^^^^^^^^^^^^^
+
+Any data error is displayed instead of the map to provide instant feedback about the input parameters. For example, the user is not authorized, the connection or the column names do not exist, etc.
+
+.. figure:: images/error-message-column.png
+
+Properties
+^^^^^^^^^^
+
+See deck.gl documentation for all `layer properties <https://deck.gl/docs/api-reference/carto/overview#carto-layers>`_.
+
+VectorTileLayer
+~~~~~~~~~~~~~~~
+
+* **data**: (``pydeck-carto.types.Source``) Source created with
+  :meth:`pydeck_carto.sources.vector_table_source`,
+  :meth:`pydeck_carto.sources.vector_query_source`, or
+  :meth:`pydeck_carto.sources.vector_tileset_source`.
+
+H3TileLayer
+~~~~~~~~~~~
+
+* **data**: (``pydeck-carto.types.Source``) Source created with
+  :meth:`pydeck_carto.sources.h3_table_source`,
+  :meth:`pydeck_carto.sources.h3_query_source`, or
+  :meth:`pydeck_carto.sources.h3_tileset_source`.
+
+QuadbinTileLayer
+~~~~~~~~~~~~~~~~
+
+* **data**: (``pydeck-carto.types.Source``) Source created with
+  :meth:`pydeck_carto.sources.quadbin_table_source`,
+  :meth:`pydeck_carto.sources.quadbin_query_source`, or
+  :meth:`pydeck_carto.sources.quadbin_tileset_source`.
+
+Reference
+^^^^^^^^^
+
+.. automodule:: pydeck_carto
+    :members:
diff --git a/bindings/pydeck-carto/docs/sources.rst b/bindings/pydeck-carto/docs/sources.rst
@@ -0,0 +1,28 @@
+CARTO Sources
+=============
+
+Sources provide data sources for CARTO layer types, and are based on `deck.gl data sources <https://deck.gl/docs/api-reference/carto/data-sources>`_.
+
+Reference
+^^^^^^^^^
+
+Vector sources
+~~~~~~~~~~~~~~
+
+.. autoclass:: pydeck_carto.sources.vector_table_source
+.. autoclass:: pydeck_carto.sources.vector_query_source
+.. autoclass:: pydeck_carto.sources.vector_tileset_source
+
+H3 sources
+~~~~~~~~~~
+
+.. autoclass:: pydeck_carto.sources.h3_table_source
+.. autoclass:: pydeck_carto.sources.h3_query_source
+.. autoclass:: pydeck_carto.sources.h3_tileset_source
+
+Quadbin sources
+~~~~~~~~~~~~~~~
+
+.. autoclass:: pydeck_carto.sources.quadbin_table_source
+.. autoclass:: pydeck_carto.sources.quadbin_query_source
+.. autoclass:: pydeck_carto.sources.quadbin_tileset_source