Improve docs

Author: FBumann

.pre-commit-config.yaml

@@ -5,6 +5,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        args: [--unsafe]
       - id: check-added-large-files
       - id: check-toml
 

README.md

@@ -24,7 +24,7 @@ uv add xarray_plotly
 ```python
 import xarray as xr
 import numpy as np
-import xarray_plotly  # registers the accessor
+from xarray_plotly import xpx
 
 # Create sample data
 da = xr.DataArray(
@@ -40,13 +40,29 @@ da = xr.DataArray(
 
 # Create an interactive line plot
 # Dimensions auto-assign: time→x, city→color, scenario→facet_col
-fig = da.plotly.line()
+fig = xpx(da).line()
 fig.show()
 
 # Easy customization
 fig.update_layout(title="Temperature Projections", template="plotly_dark")
 ```
 
+## Usage Styles
+
+xarray_plotly supports two equivalent usage styles:
+
+```python
+# Function style (recommended) - full IDE code completion
+from xarray_plotly import xpx
+fig = xpx(da).line()
+
+# Accessor style - works but no IDE completion
+import xarray_plotly
+fig = da.plotly.line()
+```
+
+The `xpx()` function is recommended as it provides full IDE code completion and type hints.
+
 ## Features
 
 - **Interactive plots**: Zoom, pan, hover for values, toggle traces
@@ -62,13 +78,13 @@ Dimensions are automatically assigned to plot "slots" based on their order:
 ```python
 # dims: (time, city, scenario)
 # auto-assigns: time→x, city→color, scenario→facet_col
-da.plotly.line()
+xpx(da).line()
 
 # Override with explicit assignments
-da.plotly.line(x="time", color="scenario", facet_col="city")
+xpx(da).line(x="time", color="scenario", facet_col="city")
 
 # Skip a slot with None
-da.plotly.line(color=None)  # time→x, city→facet_col
+xpx(da).line(color=None)  # time→x, city→facet_col
 ```
 
 ## Available Methods

docs/api.md

@@ -1,7 +1,23 @@
 # API Reference
 
+## xpx Function
+
+The recommended way to use xarray_plotly with full IDE code completion:
+
+```python
+from xarray_plotly import xpx
+
+fig = xpx(da).line()
+```
+
+::: xarray_plotly.xpx
+    options:
+      show_root_heading: true
+
 ## Accessor
 
+The accessor style (`da.plotly.line()`) works but doesn't provide IDE code completion.
+
 ::: xarray_plotly.accessor.DataArrayPlotlyAccessor
     options:
       show_root_heading: true

docs/examples/advanced.ipynb

@@ -19,7 +19,7 @@
     "import pandas as pd\n",
     "import xarray as xr\n",
     "\n",
-    "import xarray_plotly"
+    "from xarray_plotly import xpx"
    ]
   },
   {
@@ -57,7 +57,7 @@
     "da.coords[\"station\"].attrs = {\"long_name\": \"Measurement Station\"}\n",
     "\n",
     "# Labels are automatically extracted from attrs\n",
-    "fig = da.plotly.line(title=\"Temperature with Auto-Labels\")\n",
+    "fig = xpx(da).line(title=\"Temperature with Auto-Labels\")\n",
     "fig"
    ]
   },
@@ -76,7 +76,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da.plotly.line(\n",
+    "fig = xpx(da).line(\n",
     "    labels={\n",
     "        \"temperature\": \"Temp (°C)\",\n",
     "        \"time\": \"Date\",\n",
@@ -117,7 +117,7 @@
     ")\n",
     "\n",
     "# Use line_dash for one dimension, color for another\n",
-    "fig = da_complex.sel(city=\"NYC\").plotly.line(\n",
+    "fig = xpx(da_complex.sel(city=\"NYC\")).line(\n",
     "    color=\"scenario\",\n",
     "    line_dash=\"model\",\n",
     "    title=\"Multiple Visual Encodings\",\n",
@@ -141,7 +141,7 @@
    "outputs": [],
    "source": [
     "# Average over model dimension\n",
-    "fig = da_complex.mean(\"model\").plotly.line(\n",
+    "fig = xpx(da_complex.mean(\"model\")).line(\n",
     "    facet_col=\"city\",\n",
     "    title=\"Ensemble Mean by City\",\n",
     ")\n",
@@ -155,7 +155,7 @@
    "outputs": [],
    "source": [
     "# Select a specific slice\n",
-    "fig = da_complex.sel(scenario=\"SSP5\", model=\"GCM-A\").plotly.line(\n",
+    "fig = xpx(da_complex.sel(scenario=\"SSP5\", model=\"GCM-A\")).line(\n",
     "    facet_col=\"city\",\n",
     "    title=\"SSP5 / GCM-A Projections\",\n",
     ")\n",
@@ -184,7 +184,7 @@
    "source": [
     "da_simple = da.sel(station=\"Urban\")\n",
     "\n",
-    "fig = da_simple.plotly.line(\n",
+    "fig = xpx(da_simple).line(\n",
     "    template=\"plotly_dark\",\n",
     "    title=\"Dark Theme\",\n",
     ")\n",
@@ -206,7 +206,7 @@
    "source": [
     "import plotly.express as px\n",
     "\n",
-    "fig = da.plotly.line(\n",
+    "fig = xpx(da).line(\n",
     "    color_discrete_sequence=px.colors.qualitative.Set2,\n",
     "    title=\"Custom Color Palette\",\n",
     ")\n",
@@ -233,7 +233,7 @@
     ")\n",
     "\n",
     "# Diverging colorscale centered at zero\n",
-    "fig = da_2d.plotly.imshow(\n",
+    "fig = xpx(da_2d).imshow(\n",
     "    color_continuous_scale=\"RdBu_r\",\n",
     "    color_continuous_midpoint=0,\n",
     "    title=\"Diverging Colorscale\",\n",
@@ -256,7 +256,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da.plotly.line()\n",
+    "fig = xpx(da).line()\n",
     "\n",
     "# Add horizontal reference line\n",
     "fig.add_hline(y=15, line_dash=\"dash\", line_color=\"gray\", annotation_text=\"Reference\")\n",
@@ -289,7 +289,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da.plotly.line()\n",
+    "fig = xpx(da).line()\n",
     "\n",
     "# Make all lines thicker\n",
     "fig.update_traces(line_width=3)\n",
@@ -349,7 +349,7 @@
     "# Rolling mean\n",
     "da_smooth = da.rolling(time=7, center=True).mean()\n",
     "\n",
-    "fig = da_smooth.plotly.line(\n",
+    "fig = xpx(da_smooth).line(\n",
     "    title=\"7-Day Rolling Mean\",\n",
     ")\n",
     "fig"
@@ -374,7 +374,7 @@
     "\n",
     "monthly_mean = da_monthly.groupby(\"time.month\").mean()\n",
     "\n",
-    "fig = monthly_mean.plotly.line(\n",
+    "fig = xpx(monthly_mean).line(\n",
     "    title=\"Monthly Climatology\",\n",
     ")\n",
     "fig.update_xaxes(tickmode=\"array\", tickvals=list(range(1, 13)), \n",

docs/examples/plot-types.ipynb

@@ -19,7 +19,7 @@
     "import pandas as pd\n",
     "import xarray as xr\n",
     "\n",
-    "import xarray_plotly"
+    "from xarray_plotly import xpx"
    ]
   },
   {
@@ -88,7 +88,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_ts.plotly.line(title=\"Line Plot\")\n",
+    "fig = xpx(da_ts).line(title=\"Line Plot\")\n",
     "fig"
    ]
   },
@@ -105,7 +105,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_ts.plotly.line(markers=True, title=\"Line Plot with Markers\")\n",
+    "fig = xpx(da_ts).line(markers=True, title=\"Line Plot with Markers\")\n",
     "fig"
    ]
   },
@@ -124,7 +124,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_cat.plotly.bar(title=\"Stacked Bar Chart\")\n",
+    "fig = xpx(da_cat).bar(title=\"Stacked Bar Chart\")\n",
     "fig"
    ]
   },
@@ -141,7 +141,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_cat.plotly.bar(barmode=\"group\", title=\"Grouped Bar Chart\")\n",
+    "fig = xpx(da_cat).bar(barmode=\"group\", title=\"Grouped Bar Chart\")\n",
     "fig"
    ]
   },
@@ -171,7 +171,7 @@
     "    name=\"energy\",\n",
     ")\n",
     "\n",
-    "fig = da_positive.plotly.area(title=\"Stacked Area Chart\")\n",
+    "fig = xpx(da_positive).area(title=\"Stacked Area Chart\")\n",
     "fig"
    ]
   },
@@ -190,7 +190,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_ts.plotly.scatter(title=\"Scatter Plot\")\n",
+    "fig = xpx(da_ts).scatter(title=\"Scatter Plot\")\n",
     "fig"
    ]
   },
@@ -209,7 +209,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_2d.plotly.scatter(x=\"lon\", y=\"lat\", color=\"value\", title=\"Lat/Lon Scatter\")\n",
+    "fig = xpx(da_2d).scatter(x=\"lon\", y=\"lat\", color=\"value\", title=\"Lat/Lon Scatter\")\n",
     "fig"
    ]
   },
@@ -236,7 +236,7 @@
     "    name=\"response\",\n",
     ")\n",
     "\n",
-    "fig = da_dist.plotly.box(title=\"Box Plot\")\n",
+    "fig = xpx(da_dist).box(title=\"Box Plot\")\n",
     "fig"
    ]
   },
@@ -255,7 +255,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_2d.plotly.imshow(title=\"Heatmap\")\n",
+    "fig = xpx(da_2d).imshow(title=\"Heatmap\")\n",
     "fig"
    ]
   },
@@ -272,7 +272,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da_2d.plotly.imshow(\n",
+    "fig = xpx(da_2d).imshow(\n",
     "    color_continuous_scale=\"Viridis\",\n",
     "    title=\"Heatmap with Viridis colorscale\",\n",
     ")\n",
@@ -306,7 +306,7 @@
     "    name=\"value\",\n",
     ")\n",
     "\n",
-    "fig = da_3d.plotly.line(\n",
+    "fig = xpx(da_3d).line(\n",
     "    facet_col=\"city\",\n",
     "    facet_row=\"scenario\",\n",
     "    title=\"Faceted Line Plot\",\n",
@@ -341,7 +341,7 @@
     "    name=\"sales\",\n",
     ")\n",
     "\n",
-    "fig = da_monthly.plotly.bar(\n",
+    "fig = xpx(da_monthly).bar(\n",
     "    x=\"product\",\n",
     "    animation_frame=\"month\",\n",
     "    title=\"Monthly Sales (Animated)\",\n",

docs/getting-started.ipynb

@@ -32,7 +32,7 @@
    "source": [
     "## Basic Usage\n",
     "\n",
-    "Import the package to register the `plotly` accessor:"
+    "Import the `xpx` function for full IDE code completion:"
    ]
   },
   {
@@ -45,7 +45,7 @@
     "import pandas as pd\n",
     "import xarray as xr\n",
     "\n",
-    "import xarray_plotly  # Registers the .plotly accessor"
+    "from xarray_plotly import xpx  # Provides full IDE code completion"
    ]
   },
   {
@@ -97,7 +97,7 @@
    "outputs": [],
    "source": [
     "# Dimensions auto-assign: time→x, city→color, scenario→facet_col\n",
-    "fig = da.plotly.line()\n",
+    "fig = xpx(da).line()\n",
     "fig"
    ]
   },
@@ -136,7 +136,7 @@
    "outputs": [],
    "source": [
     "# Put scenario on color, city on facets\n",
-    "fig = da.plotly.line(color=\"scenario\", facet_col=\"city\")\n",
+    "fig = xpx(da).line(color=\"scenario\", facet_col=\"city\")\n",
     "fig"
    ]
   },
@@ -156,7 +156,7 @@
    "outputs": [],
    "source": [
     "# Skip color, so city goes to line_dash instead\n",
-    "fig = da.sel(scenario=\"baseline\").plotly.line(color=None)\n",
+    "fig = xpx(da.sel(scenario=\"baseline\")).line(color=None)\n",
     "fig"
    ]
   },
@@ -175,7 +175,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da.plotly.line()\n",
+    "fig = xpx(da).line()\n",
     "\n",
     "fig.update_layout(\n",
     "    title=\"Temperature Anomaly Projections\",\n",
@@ -199,7 +199,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "fig = da.plotly.line(\n",
+    "fig = xpx(da).line(\n",
     "    title=\"Temperature Trends\",\n",
     "    color_discrete_sequence=[\"#E63946\", \"#457B9D\", \"#2A9D8F\"],\n",
     "    template=\"simple_white\",\n",