Remove duplication from docs and docstrings

Author: FBumann

docs/api.md

@@ -2,22 +2,12 @@
 
 ## 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
@@ -44,31 +34,6 @@ The accessor style (`da.plotly.line()`) works but doesn't provide IDE code compl
 
 ## Configuration
 
-Customize label extraction and slot assignment behavior:
-
-```python
-from xarray_plotly import config, xpx
-
-# View current options
-config.get_options()
-
-# Set options (works as context manager)
-with config.set_options(label_include_units=False):
-    fig = xpx(da).line()
-```
-
-For all other visual customization (themes, colors, default template, etc.),
-use Plotly's built-in configuration via `plotly.io`:
-
-```python
-import plotly.io as pio
-
-pio.templates.default = "plotly_white"
-pio.renderers.default = "notebook"
-```
-
-See [Plotly Templates](https://plotly.com/python/templates/) for available options.
-
 ::: xarray_plotly.config
     options:
       show_root_heading: true

docs/index.md

@@ -2,89 +2,43 @@
 
 **Interactive Plotly Express plotting accessor for xarray**
 
-xarray_plotly provides interactive plotting for xarray DataArray objects using Plotly Express. It automatically assigns dimensions to plot slots based on their order, making it easy to create rich, interactive visualizations with minimal code.
+::: xarray_plotly
+    options:
+      show_root_heading: false
+      show_docstring_description: true
+      show_docstring_examples: true
+      members: false
 
-## Features
+## Installation
 
-- **Interactive plots**: Zoom, pan, hover for values, toggle traces - all built-in
-- **Automatic dimension assignment**: Dimensions fill plot slots (x, color, facet_col, etc.) by position
-- **Easy customization**: Returns Plotly `Figure` objects for further modification
-- **Multiple plot types**: Line, bar, area, scatter, box, and heatmap plots
-- **Faceting and animation**: Built-in support for subplot grids and animated time series
-- **Full IDE support**: The `xpx()` function provides complete code completion and type hints
+```bash
+pip install xarray_plotly
+```
 
-## Quick Example
+## Usage
 
 ```python
 import xarray as xr
 import numpy as np
-from xarray_plotly import xpx
+import xarray_plotly  # registers the accessor
 
-# Create sample data
 da = xr.DataArray(
-    np.random.randn(100, 3, 2),
-    dims=["time", "city", "scenario"],
-    coords={
-        "time": np.arange(100),
-        "city": ["NYC", "LA", "Chicago"],
-        "scenario": ["baseline", "warming"],
-    },
-    name="temperature",
+    np.random.randn(100, 3).cumsum(axis=0),
+    dims=["time", "city"],
+    coords={"time": np.arange(100), "city": ["NYC", "LA", "Chicago"]},
 )
 
-# Create an interactive line plot
-# Dimensions auto-assign: time->x, city->color, scenario->facet_col
-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:
+# Accessor style
+fig = da.plotly.line()
 
-```python
-# Function style (recommended) - full IDE code completion
+# Or with xpx() for 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.
-
-**Why no IDE completion for the accessor?** xarray accessors are registered dynamically at runtime using `register_dataarray_accessor()`. Python's static type checkers and IDEs cannot see these dynamically added attributes, so `da.plotly` appears as an unknown attribute. This limitation could only be solved by xarray itself (e.g., through a type checker plugin), if at all. The `xpx()` function provides a workaround with an explicit return type that IDEs can follow.
-
-## Installation
-
-```bash
-pip install xarray_plotly
-```
-
-Or with uv:
-
-```bash
-uv add xarray_plotly
-```
-
-## Why xarray_plotly?
-
-The current `.plot` accessor in xarray is built on matplotlib, which has limitations for modern data exploration:
-
-1. **Static outputs**: Matplotlib plots are non-interactive
-2. **Post-creation modification is cumbersome**: Requires understanding complex object hierarchies
-3. **Multi-dimensional data**: No built-in support for faceting or animation
-
-xarray_plotly solves these with Plotly Express, providing:
+## Next Steps
 
-- Interactive plots with zero additional code
-- Simple, predictable dimension-to-slot assignment
-- Easy post-creation customization via Plotly's `Figure` API
-- Modern visualization patterns (faceting, animation) built-in
+- [Getting Started](getting-started.ipynb) - Interactive tutorial
+- [Plot Types](examples/plot-types.ipynb) - All available plot types
+- [Advanced Usage](examples/advanced.ipynb) - Configuration and customization
+- [API Reference](api.md) - Full API documentation

xarray_plotly/__init__.py

@@ -1,8 +1,28 @@
 """
 xarray_plotly: Interactive Plotly Express plotting for xarray.
 
-This package provides interactive plotting for xarray DataArray objects
-using Plotly Express.
+This package provides a `plotly` accessor for xarray DataArray objects,
+enabling interactive visualization with Plotly Express.
+
+Features
+--------
+- **Interactive plots**: Zoom, pan, hover, toggle traces
+- **Automatic dimension assignment**: Dimensions fill slots (x, color, facet) by position
+- **Multiple plot types**: line, bar, area, scatter, box, imshow
+- **Faceting and animation**: Built-in subplot grids and animated plots
+- **Customizable**: Returns Plotly Figure objects for further modification
+
+Usage
+-----
+Accessor style::
+
+    import xarray_plotly
+    fig = da.plotly.line()
+
+Function style (recommended for IDE completion)::
+
+    from xarray_plotly import xpx
+    fig = xpx(da).line()
 
 Examples
 --------
@@ -21,8 +41,8 @@
 >>> # Explicit assignment
 >>> fig = xpx(da).line(x="time", color="scenario", facet_col="city")
 
->>> # Skip a slot
->>> fig = xpx(da).line(color=None)  # time->x, city->facet_col, scenario->facet_row
+>>> # Skip a slot with None
+>>> fig = xpx(da).line(color=None)
 """
 
 from importlib.metadata import version

xarray_plotly/accessor.py

@@ -13,20 +13,40 @@
 
 class DataArrayPlotlyAccessor:
     """
-    Enables use of Plotly Express plotting functions on a DataArray.
+    Plotly Express plotting accessor for xarray DataArray.
 
-    Methods return Plotly Figure objects for interactive visualization.
+    Dimensions are automatically assigned to plot slots by position.
+    All methods return Plotly Figure objects for interactive visualization.
+
+    Available methods: line, bar, area, scatter, box, imshow
+
+    Parameters
+    ----------
+    darray : DataArray
+        The DataArray to plot.
 
     Examples
     --------
     >>> import xarray as xr
     >>> import numpy as np
     >>> da = xr.DataArray(np.random.rand(10, 3), dims=["time", "city"])
-    >>> fig = da.plotly.line()  # Auto-assign dims: time->x, city->color
-    >>> fig.show()
 
-    >>> fig = da.plotly.line(x="time", color=None)  # Explicit assignment
-    >>> fig.update_layout(title="My Plot")
+    Auto-assign dimensions to slots:
+
+    >>> fig = da.plotly.line()  # time->x, city->color
+
+    Explicit slot assignment:
+
+    >>> fig = da.plotly.line(color="time", x="city")
+
+    Skip a slot with None:
+
+    >>> fig = da.plotly.line(color=None)  # time->x, city->line_dash
+
+    Customize the returned Figure:
+
+    >>> fig = da.plotly.line()
+    >>> fig.update_layout(title="My Plot", template="plotly_dark")
     """
 
     __all__: ClassVar = ["line", "bar", "area", "scatter", "box", "imshow"]

xarray_plotly/common.py

@@ -81,6 +81,17 @@ def assign_slots(
     ValueError
         If plot_type is unknown, a dimension doesn't exist, or dimensions
         are left unassigned (unless allow_unassigned=True).
+
+    Examples
+    --------
+    >>> assign_slots(["time", "city", "scenario"], "line")
+    {'x': 'time', 'color': 'city', 'line_dash': 'scenario'}
+
+    >>> assign_slots(["time", "city"], "line", color="time", x="city")
+    {'x': 'city', 'color': 'time'}
+
+    >>> assign_slots(["time", "city", "scenario"], "line", color=None)
+    {'x': 'time', 'line_dash': 'city', 'symbol': 'scenario'}
     """
     slot_orders = _options.slot_orders
     if plot_type not in slot_orders: