From 7557977b17f27251d9639ff82a2ac16e8885d3f3 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 2 Sep 2026 22:00:29 +0000 Subject: [PATCH] Add API docs section and llms.txt for GitHub Pages Document the dash-globe Python API on the docs site, add markdown siblings for agents, and publish an llms.txt entry point per llmstxt.org. Co-authored-by: Jeff --- docs/README.md | 19 ++ docs/api.html | 377 ++++++++++++++++++++++++++++++++++++++ docs/api.md | 117 ++++++++++++ docs/assets/site.css | 118 ++++++++++++ docs/examples.html | 8 +- docs/examples.md | 27 +++ docs/getting-started.html | 8 +- docs/getting-started.md | 76 ++++++++ docs/index.html | 7 +- docs/index.md | 35 ++++ docs/llms.txt | 31 ++++ 11 files changed, 818 insertions(+), 5 deletions(-) create mode 100644 docs/api.html create mode 100644 docs/api.md create mode 100644 docs/examples.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/llms.txt diff --git a/docs/README.md b/docs/README.md index 77ca8f6..aa1bc09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,19 @@ This directory is published to **https://jeffgallini.github.io/dash-globe/** by [`.github/workflows/docs.yml`](../.github/workflows/docs.yml). +## Pages + +| Path | Purpose | +| --- | --- | +| `index.html` / `index.md` | Home | +| `getting-started.html` / `getting-started.md` | Quick start | +| `api.html` / `api.md` | Python API reference | +| `examples.html` / `examples.md` | Example gallery | +| `llms.txt` | LLM-oriented site map ([llms.txt spec](https://llmstxt.org/)) | + +Markdown siblings and `llms.txt` are for agents; HTML pages include +`rel="alternate"` / `rel="describedby"` links to them. + ## Local preview Open `docs/index.html` in a browser, or: @@ -11,6 +24,12 @@ Open `docs/index.html` in a browser, or: python -m http.server 8080 --directory docs ``` +Then visit: + +- http://127.0.0.1:8080/ +- http://127.0.0.1:8080/api.html +- http://127.0.0.1:8080/llms.txt + ## Refresh example media With the gallery running (`python dash_globe/usage.py`): diff --git a/docs/api.html b/docs/api.html new file mode 100644 index 0000000..0326a52 --- /dev/null +++ b/docs/api.html @@ -0,0 +1,377 @@ + + + + + + API · Dash Globe + + + + + + +
+
+ + + Dash Globe + + +
+
+ +
+
Reference
+

Python API

+

+ dash-globe wraps react-globe.gl + with a chainable, figure-like Python API. Configure layout, textures, camera, and layers in fluent + calls, then wire clickData / hoverData into normal Dash callbacks. +

+ +
+ + +
+
+

Imports

+ 
import dash_globe
+
+globe = dash_globe.DashGlobe(id="globe")
+# Helpers
+dash_globe.PRESETS
+dash_globe.data_url(...)
+dash_globe.event_coords(...)
+dash_globe.material_spec(...)
+dash_globe.lambert_material(...)
+dash_globe.ring_color_interpolator(...)
+

+ Install with pip install dash-globe. Public exports are listed in + dash_globe.__all__. +

+
+ +
+

DashGlobe

+

+ Subclasses the generated Dash component. Defaults responsive=True. + All helpers return self so calls chain. +

+ +
+

DashGlobe(*args, **kwargs)

+

Create a globe component. Pass any raw react-globe.gl prop alongside high-level helpers.

+ 
dash_globe.DashGlobe(id="demo", responsive=True)
+
+ +
+

update(**kwargs)

+

+ Set component props in place. Snake-case aliases are accepted for camelCase props + (for example background_color → backgroundColor). +

+
+
+ +
+

Scene helpers

+ +
+

update_layout(...)

+

Outer layout and renderer settings.

+ + + + + + + + + + + + +
ParameterDescription
width, heightCanvas size in pixels.
responsiveResize with the container.
background_colorCSS color behind the canvas.
background_image_urlBackground image URL.
globe_offset[x, y] offset from canvas center.
wait_for_globe_readyDefer animation until assets load.
animate_inInitial entrance animation.
renderer_config, style, class_nameRenderer / wrapper extras.
+
+ +
+

update_globe(...)

+

Globe shell texture and atmosphere.

+ + + + + + + + +
ParameterDescription
globe_image_url, bump_image_urlBase and bump textures.
show_globe, show_graticules, show_atmosphereVisibility toggles.
atmosphere_color, atmosphere_altitudeAtmosphere styling.
curvature_resolutionMesh curvature resolution.
+
+ +
+

update_view(lat=, lng=, altitude=, transition_duration=)

+

Set camera target. Omitted fields keep their current values.

+
+ +
+

update_controls(auto_rotate=, auto_rotate_speed=)

+

Orbit control auto-rotation.

+
+ +
+

update_interaction(...)

+

+ Pointer picking, cursor style, line hover precision, animation pause, and + currentView report interval. +

+
+ +
+

update_day_night_cycle(...)

+

+ Built-in day/night shader: + enabled, day_image_url, night_image_url, + time, animate, minutes_per_second. +

+
+ +
+

update_clouds(...)

+

+ Rotating cloud shell: + enabled, image_url, altitude, + rotation_speed, opacity. +

+
+ +
+

clear_tile_cache()

+

Bump clearGlobeTileCacheKey so the client refreshes cached tiles.

+
+
+ +
+

Layers

+

+ Each layer has an add_* helper that appends records and an + update_* helper that replaces data and/or sets accessors. + Pass a single list or multiple positional records to add_*. +

+ +
+

Points

+ 
.add_points(*points)
+.update_points(data=None, **props)
+

Common props: point_lat, point_lng, point_color, point_label, point_altitude, point_radius.

+
+ +
+

Arcs

+ 
.add_arcs(*arcs)
+.update_arcs(data=None, **props)
+

Common props: arc_start_lat, arc_start_lng, arc_end_lat, arc_end_lng, arc_color, arc_dash_length, arc_dash_gap, arc_dash_animate_time.

+
+ +
+

Polygons

+ 
.add_polygons(*polygons)
+.update_polygons(data=None, **props)
+

Common props: polygon_geo_json_geometry, polygon_cap_color, polygon_side_color, polygon_stroke_color, polygon_altitude, polygon_label.

+
+ +
+

Paths

+ 
.add_paths(*paths)
+.update_paths(data=None, path_points=..., path_color=..., ...)
+
+ +
+

Heatmaps

+ 
.add_heatmap(points)
+.add_heatmaps(*heatmaps)
+.update_heatmap(data=None, **props)
+.update_heatmaps(data=None, **props)
+
+ +
+

Hex bins & hex polygons

+ 
.add_hex_bins(*points) / .update_hex_bins(...)
+.add_hex_polygons(*polygons) / .update_hex_polygons(...)
+
+ +
+

Tiles

+ 
.add_tiles(*tiles)
+.update_tiles(data=None, tile_material=..., ...)
+

Use material_spec(...) or lambert_material(...) for JSON-serialisable materials.

+
+ +
+

Particles

+ 
.add_particle_sets(*particle_sets)
+.update_particles(data=None, **props)
+
+ +
+

Rings

+ 
.add_rings(*rings)
+.update_rings(data=None, ring_color=..., ...)
+

Animated ring colors can use ring_color_interpolator(...) instead of a JS callback.

+
+ +
+

Labels

+ 
.add_labels(*labels)
+.update_labels(data=None, label_text=..., ...)
+
+ +
+

HTML overlays

+ 
.add_html_elements(*elements, children=None)
+.update_html_elements(data=None, children=None, **props)
+

Geo-anchored Dash children matched to htmlElementsData by index.

+
+
+ +
+

Large data

+
+

enable_large_data_mode(enabled=True, **props)

+

+ Enables client-side large-data defaults (summary event payloads, merged point/hex + rendering, disabled layer transitions). Pair with data_url(...). +

+
+
+

dash_globe.data_url(url, unwrap_features=True)

+

+ Returns a compact marker the React wrapper fetches in the browser so large GeoJSON + never enters the Dash layout. GeoJSON FeatureCollections are unwrapped to + .features by default. +

+ 
.update_polygons(
+    data=dash_globe.data_url("https://example.com/countries.geojson"),
+    polygon_geo_json_geometry="geometry",
+    polygon_cap_color="steelblue",
+)
+
+
+ +
+

Helpers

+ +
+

PRESETS

+

Built-in texture URLs:

+ + + + + + + + +
AttributeUse
EARTH, EARTH_DAY, EARTH_NIGHT, EARTH_DARKGlobe textures
EARTH_TOPOGRAPHY, EARTH_WATERBump / water masks
NIGHT_SKYBackground starfield
CLOUDSCloud shell texture
+
+ +
+

event_coords(event)

+

+ Extract {"lat", "lng", "altitude?"} from a clickData / + hoverData payload. Returns None when coordinates are missing. +

+
+ +
+

material_spec(type, **options) / lambert_material(...)

+

+ JSON material specs for tile layers. Types: + basic, lambert, phong, standard. + Side: front, back, double. +

+
+ +
+

ring_color_interpolator(color, fade_color=, opacity=, fade_opacity=, easing=)

+

+ Serialisable stand-in for a JS ringColor callback. + Easing: linear, sqrt, square, cubic. +

+
+
+ +
+

Events & callbacks

+

+ These props participate in normal Dash callbacks as Inputs/States: +

+ + + + + + + + + +
PropMeaning
clickDataLast left-click pick payload
rightClickDataLast right-click pick payload
hoverDataCurrent hover pick payload
currentViewReported camera view (lat/lng/altitude)
eventDataMode"summary" or "full" payload size
+ 
from dash import Input, Output, callback
+import dash_globe
+
+@callback(Output("out", "children"), Input("globe", "clickData"))
+def on_click(click_data):
+    coords = dash_globe.event_coords(click_data)
+    return str(coords)
+
+ +
+

Accessors & naming

+

+ Layer accessors accept either a constant value or a string field path + (for example "lat" or "properties.ADMIN"). + High-level helpers accept snake_case; raw camelCase props also work via + update(...) or the constructor. +

+
+ The wrapper targets JSON-serialisable react-globe.gl features. + Raw JavaScript functions, DOM nodes, and arbitrary Three.js objects are not + exposed through the high-level helpers. +
+
+ Getting started + Examples + Markdown API +
+
+
+
+
+ + + + diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..832ad9b --- /dev/null +++ b/docs/api.md @@ -0,0 +1,117 @@ +# Dash Globe Python API + +> Chainable Python API for building interactive 3D globes in Dash on top of [react-globe.gl](https://github.com/vasturiano/react-globe.gl). + +Install: `pip install dash-globe` + +HTML version: [api.html](./api.html) + +## Imports + +```python +import dash_globe + +globe = dash_globe.DashGlobe(id="globe") +dash_globe.PRESETS +dash_globe.data_url(...) +dash_globe.event_coords(...) +dash_globe.material_spec(...) +dash_globe.lambert_material(...) +dash_globe.ring_color_interpolator(...) +``` + +Public exports: `DashGlobe`, `PRESETS`, `data_url`, `is_data_url`, `event_coords`, `ring_color_interpolator`, `material_spec`, `lambert_material`. + +## DashGlobe + +`DashGlobe(*args, **kwargs)` subclasses the generated Dash component and defaults `responsive=True`. Every helper returns `self` for chaining. + +`update(**kwargs)` sets props in place. Snake-case aliases map to camelCase component props (`background_color` → `backgroundColor`). + +### Scene helpers + +- `update_layout(width=, height=, responsive=, background_color=, background_image_url=, globe_offset=, wait_for_globe_ready=, animate_in=, renderer_config=, style=, class_name=)` +- `update_globe(globe_image_url=, bump_image_url=, show_globe=, show_graticules=, show_atmosphere=, atmosphere_color=, atmosphere_altitude=, curvature_resolution=)` +- `update_view(lat=, lng=, altitude=, transition_duration=)` +- `update_controls(auto_rotate=, auto_rotate_speed=)` +- `update_interaction(enable_pointer_interaction=, show_pointer_cursor=, line_hover_precision=, animation_paused=, current_view_report_interval=)` +- `update_day_night_cycle(enabled=, day_image_url=, night_image_url=, time=, animate=, minutes_per_second=)` +- `update_clouds(enabled=, image_url=, altitude=, rotation_speed=, opacity=)` +- `clear_tile_cache()` + +### Layers + +Each layer supports `add_*` (append) and `update_*` (replace data / set accessors): + +| Layer | Methods | +| --- | --- | +| Points | `add_points`, `update_points` | +| Arcs | `add_arcs`, `update_arcs` | +| Polygons | `add_polygons`, `update_polygons` | +| Paths | `add_paths`, `update_paths` | +| Heatmaps | `add_heatmap`, `add_heatmaps`, `update_heatmap`, `update_heatmaps` | +| Hex bins | `add_hex_bins`, `update_hex_bins` | +| Hex polygons | `add_hex_polygons`, `update_hex_polygons` | +| Tiles | `add_tiles`, `update_tiles` | +| Particles | `add_particle_sets`, `update_particles` | +| Rings | `add_rings`, `update_rings` | +| Labels | `add_labels`, `update_labels` | +| HTML overlays | `add_html_elements`, `update_html_elements` | + +Accessors accept constants or string field paths (`"lat"`, `"properties.ADMIN"`). + +### Large data + +```python +globe = ( + dash_globe.DashGlobe(id="countries") + .enable_large_data_mode() + .update_polygons( + data=dash_globe.data_url( + "https://raw.githubusercontent.com/vasturiano/react-globe.gl/master/example/datasets/ne_110m_admin_0_countries.geojson" + ), + polygon_geo_json_geometry="geometry", + polygon_cap_color="rgba(56, 189, 248, 0.55)", + polygon_label="properties.ADMIN", + ) +) +``` + +`data_url(url, unwrap_features=True)` builds a client-fetch marker so large GeoJSON never enters the Dash layout. `enable_large_data_mode()` turns on summary event payloads and other large-data defaults. + +## Helpers + +### PRESETS + +Texture URLs: `EARTH`, `EARTH_DAY`, `EARTH_NIGHT`, `EARTH_DARK`, `EARTH_TOPOGRAPHY`, `EARTH_WATER`, `NIGHT_SKY`, `CLOUDS`. + +### event_coords(event) + +Returns `{"lat", "lng", "altitude?"}` from `clickData` / `hoverData`, or `None`. + +### material_spec / lambert_material + +JSON material specs for tiles. Types: `basic`, `lambert`, `phong`, `standard`. Side: `front`, `back`, `double`. + +### ring_color_interpolator + +Serialisable ring fade spec. Easing: `linear`, `sqrt`, `square`, `cubic`. + +## Events + +Dash callback props: `clickData`, `rightClickData`, `hoverData`, `currentView`. Payload size controlled by `eventDataMode` (`"summary"` | `"full"`). + +```python +from dash import Input, Output, callback +import dash_globe + +@callback(Output("out", "children"), Input("globe", "clickData")) +def on_click(click_data): + return str(dash_globe.event_coords(click_data)) +``` + +## Notes + +- Focus is JSON-serialisable `react-globe.gl` features that map cleanly to Dash. +- Raw JS functions, DOM nodes, and arbitrary Three.js objects are not exposed through high-level helpers. +- Source: [dash_globe/globe.py](https://github.com/jeffgallini/dash-globe/blob/master/dash_globe/dash_globe/globe.py) diff --git a/docs/assets/site.css b/docs/assets/site.css index 0c605f4..cc02acb 100644 --- a/docs/assets/site.css +++ b/docs/assets/site.css @@ -246,9 +246,127 @@ h3 { font-size: 1.15rem; margin-bottom: 0.45rem; } flex-wrap: wrap; } +.api-layout { + display: grid; + grid-template-columns: 220px minmax(0, 1fr); + gap: 2rem; + align-items: start; +} + +.api-toc { + position: sticky; + top: 88px; + padding: 1rem; + border: 1px solid var(--border); + border-radius: 14px; + background: rgba(19, 35, 56, 0.72); +} + +.api-toc h2 { + font-size: 0.85rem; + letter-spacing: 0.08em; + text-transform: uppercase; + color: var(--muted); + margin-bottom: 0.85rem; +} + +.api-toc nav { + display: flex; + flex-direction: column; + gap: 0.55rem; +} + +.api-toc a { + color: var(--muted); + font-size: 0.92rem; +} + +.api-toc a:hover { + color: var(--text); +} + +.api-section + .api-section { + margin-top: 2.5rem; + padding-top: 2rem; + border-top: 1px solid var(--border); +} + +.method { + margin: 1.25rem 0; + padding: 1rem 1.1rem; + border: 1px solid var(--border); + border-radius: 14px; + background: rgba(7, 17, 29, 0.72); +} + +.method h3 { + font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; + font-size: 1rem; + color: #d7e6f7; +} + +.method p { + color: var(--muted); + line-height: 1.65; + margin: 0.65rem 0 0; +} + +.method .sig { + margin-top: 0.75rem; + overflow-x: auto; + padding: 0.7rem 0.85rem; + border-radius: 10px; + border: 1px solid var(--border); + background: #050d16; + color: #9fd0ff; + font-size: 0.84rem; + line-height: 1.5; +} + +.param-table { + width: 100%; + border-collapse: collapse; + margin-top: 0.9rem; + font-size: 0.9rem; +} + +.param-table th, +.param-table td { + text-align: left; + vertical-align: top; + padding: 0.55rem 0.45rem; + border-bottom: 1px solid var(--border); +} + +.param-table th { + color: var(--muted); + font-weight: 650; +} + +.param-table code { + color: #d7e6f7; +} + +.note { + margin-top: 1rem; + padding: 0.9rem 1rem; + border-left: 3px solid var(--accent); + background: rgba(77, 163, 255, 0.08); + color: var(--muted); + line-height: 1.65; +} + @media (max-width: 900px) { .hero { grid-template-columns: 1fr; padding-top: 2.5rem; } + + .api-layout { + grid-template-columns: 1fr; + } + + .api-toc { + position: static; + } } diff --git a/docs/examples.html b/docs/examples.html index 64bd71f..f46995f 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -5,18 +5,22 @@ Examples · Dash Globe + +
- + Dash Globe @@ -100,7 +104,7 @@

Run the interactive gallery

diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..26dd7f9 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,27 @@ +# Examples · Dash Globe + +> Captured from the interactive `usage.py` gallery. Prefer GIFs where the scene animates; otherwise a still PNG shows the rendered state. + +HTML version: [examples.html](./examples.html) + +## Gallery + +- **Basic Points** — Night-earth texture with random colored altitude points (`assets/examples/basic-points.png`) +- **Random Arcs** — Dashed arcs with per-arc dash timing authored in Python (`assets/examples/random-arcs.gif`) +- **Choropleth Countries** — GDP-per-capita coloring with clientside hover highlight (`assets/examples/choropleth.png`) +- **Large Dataset via data_url** — Browser-fetched GeoJSON with summary hover payloads (`assets/examples/large-dataset.gif`) +- **Airline Routes** — OpenFlights-derived routes with hover highlighting (`assets/examples/airline-routes.png`) +- **Day Night Cycle** — First-class day/night shader mode (`assets/examples/day-night-cycle.gif`) +- **Clouds** — Rotating transparent cloud shell (`assets/examples/clouds.gif`) +- **Situation Room** — Camera-aware tethered HTML overlays for briefing-style scenes (`assets/examples/situation-room.png`) + +## Run the interactive gallery + +```bash +cd dash_globe +python usage.py +``` + +Source: [usage.py](https://github.com/jeffgallini/dash-globe/blob/master/dash_globe/usage.py) + +See also: [API reference](./api.md), [Getting started](./getting-started.md), [llms.txt](./llms.txt). diff --git a/docs/getting-started.html b/docs/getting-started.html index 39c218f..27c1481 100644 --- a/docs/getting-started.html +++ b/docs/getting-started.html @@ -5,18 +5,22 @@ Getting Started · Dash Globe + +
- + Dash Globe @@ -99,7 +103,7 @@

Local docs gallery

diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..5f863ab --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,76 @@ +# Getting Started · Dash Globe + +> Install from PyPI, configure with chainable helpers, and wire events like any other Dash component. + +HTML version: [getting-started.html](./getting-started.html) + +## Install + +```bash +pip install dash-globe +``` + +## Minimal app + +```python +from dash import Dash, html +import dash_globe + +app = Dash(__name__) + +globe = ( + dash_globe.DashGlobe(id="globe") + .update_layout(height=520, background_color="#020817") + .update_globe(globe_image_url=dash_globe.PRESETS.EARTH_NIGHT, show_atmosphere=True) + .update_controls(auto_rotate=True, auto_rotate_speed=0.4) + .add_points([ + {"name": "New York", "lat": 40.7128, "lng": -74.0060, "color": "#ff6b6b"}, + {"name": "London", "lat": 51.5072, "lng": -0.1276, "color": "#ffd166"}, + {"name": "Tokyo", "lat": 35.6762, "lng": 139.6503, "color": "#4cc9f0"}, + ]) + .update_points( + point_lat="lat", + point_lng="lng", + point_color="color", + point_label="name", + point_altitude=0.08, + point_radius=0.28, + ) +) + +app.layout = html.Div(globe) + +if __name__ == "__main__": + app.run(debug=True) +``` + +## Large GeoJSON without bloating the layout + +```python +globe = ( + dash_globe.DashGlobe(id="countries") + .enable_large_data_mode() + .update_polygons( + data=dash_globe.data_url( + "https://raw.githubusercontent.com/vasturiano/react-globe.gl/master/example/datasets/ne_110m_admin_0_countries.geojson" + ), + polygon_geo_json_geometry="geometry", + polygon_cap_color="rgba(56, 189, 248, 0.55)", + polygon_side_color="rgba(14, 165, 233, 0.12)", + polygon_stroke_color="#0f172a", + polygon_altitude=0.06, + polygon_label="properties.ADMIN", + ) +) +``` + +## Local docs gallery + +```bash +cd dash_globe +python usage.py +``` + +Then open `http://127.0.0.1:8050`. Set `DASH_GLOBE_DEBUG=1` for Dash debug tooling. + +See also: [API reference](./api.md), [llms.txt](./llms.txt). diff --git a/docs/index.html b/docs/index.html index 20504bc..8d58fac 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,6 +6,8 @@ Dash Globe · Interactive 3D globes for Dash + +
@@ -17,7 +19,9 @@ @@ -35,8 +39,9 @@

Interactive 3D globes for Dash

Get started + API reference Browse examples - Live gallery source + Live gallery source
diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..179feb6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,35 @@ +# Dash Globe · Interactive 3D globes for Dash + +> A figure-like Python API around [react-globe.gl](https://github.com/vasturiano/react-globe.gl). Chain helpers, map your data with accessors, and wire globe events into normal Dash callbacks. + +HTML version: [index.html](./index.html) + +## Why Dash Globe + +Built for Dash developers who want globe visualizations without dropping into raw Three.js. The 1.0 release locks in the chainable API, large-data helpers, and a docs-ready example gallery. + +- **Figure-like API** — `update_layout`, `update_globe`, `add_points`, `add_arcs`, and more — all chainable. +- **Full layer coverage** — Points, arcs, polygons, paths, heatmaps, hex bins, tiles, particles, rings, and labels. +- **Dash-native events** — `clickData`, `hoverData`, `rightClickData`, and `currentView` participate in normal callbacks. +- **Large data ready** — `data_url(...)` and `enable_large_data_mode()` keep GeoJSON out of the Dash layout. + +## Install + +```bash +pip install dash-globe +``` + +## Featured examples + +Screenshots and short loops from the interactive gallery. Run the full gallery locally with `python usage.py`. + +- Large Dataset — Client-fetched GeoJSON with compact summary hover payloads +- Choropleth — GDP-per-capita country coloring with hover highlighting +- Day / Night — First-class day-night shader without raw Three.js materials + +## Docs for agents + +- [llms.txt](./llms.txt) — curated entry point for LLMs ([spec](https://llmstxt.org/)) +- [API (markdown)](./api.md) +- [Getting started (markdown)](./getting-started.md) +- [Examples (markdown)](./examples.md) diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000..ab69af4 --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,31 @@ +# Dash Globe + +> Dash Globe is a Python package that wraps react-globe.gl for Plotly Dash, exposing a chainable figure-like API for interactive 3D globes. + +Important notes: + +- Install with `pip install dash-globe`. Import as `import dash_globe`. +- Prefer the high-level chainable helpers on `dash_globe.DashGlobe` (`update_layout`, `update_globe`, `add_points`, `update_points`, etc.). Snake_case aliases are accepted for camelCase props. +- For large GeoJSON, use `dash_globe.data_url(url)` plus `.enable_large_data_mode()` so payloads are fetched in the browser instead of embedded in the Dash layout. +- Event props for callbacks: `clickData`, `rightClickData`, `hoverData`, `currentView`. Use `dash_globe.event_coords(event)` to extract `{lat, lng, altitude?}`. +- The wrapper targets JSON-serialisable react-globe.gl features. Raw JavaScript callbacks, DOM nodes, and arbitrary Three.js objects are not exposed through the high-level helpers. +- Docs site root: https://jeffgallini.github.io/dash-globe/ + +## Docs + +- [API reference (markdown)](https://jeffgallini.github.io/dash-globe/api.md): Full Python API for DashGlobe helpers, layers, large-data utilities, presets, materials, and events +- [Getting started (markdown)](https://jeffgallini.github.io/dash-globe/getting-started.md): Install, minimal app, and large GeoJSON quick start +- [Examples gallery (markdown)](https://jeffgallini.github.io/dash-globe/examples.md): Captured examples from the interactive usage.py gallery +- [Home (markdown)](https://jeffgallini.github.io/dash-globe/index.md): Project overview and feature summary + +## Examples + +- [Interactive gallery source](https://github.com/jeffgallini/dash-globe/blob/master/dash_globe/usage.py): Runnable Dash app demonstrating points, arcs, choropleth, large data, day/night, clouds, and more +- [Package README](https://github.com/jeffgallini/dash-globe/blob/master/README.md): Repository overview and development notes + +## Optional + +- [HTML API page](https://jeffgallini.github.io/dash-globe/api.html): Human-oriented API documentation +- [react-globe.gl](https://github.com/vasturiano/react-globe.gl): Upstream React globe library that Dash Globe wraps +- [PyPI package](https://pypi.org/project/dash-globe/): Published package metadata and versions +- [llms.txt specification](https://llmstxt.org/): Format used by this file