Reorganize Plotting extension user guide

doc/explanation/hvplot_backend_support.ipynb

@@ -0,0 +1,73 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "360bd599",
+   "metadata": {},
+   "source": [
+    "# How hvPlot Supports Multiple Plotting Backends\n",
+    "\n",
+    "hvPlot provides a unified API for creating interactive visualizations using different plotting libraries, including [Bokeh](https://docs.bokeh.org), [Matplotlib](https://matplotlib.org/), and [Plotly](https://plotly.com/). This flexibility is made possible by its integration with [HoloViews](https://holoviews.org/), which acts as an abstraction layer for rendering plots."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f27d8593",
+   "metadata": {},
+   "source": [
+    "## hvPlot Architecture\n",
+    "\n",
+    "When you use hvPlot (e.g. `df.hvplot.line()`), hvPlot creates a HoloViews object that can be rendered by any supported backend. The choice of backend is controlled by the `extension()` and `output()` functions."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fcbd6dcc",
+   "metadata": {},
+   "source": [
+    "## Switching Backends\n",
+    "\n",
+    "You can switch between backends (e.g., Bokeh and Matplotlib) at any point in your notebook using `hvplot.output(backend=...)`. This allows you to reuse the same plotting code with different visual styles and interactive capabilities. For step-by-step instructions, see the [How-to guide on Loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "75356549",
+   "metadata": {},
+   "source": [
+    "## Styling and Compatibility Mode\n",
+    "\n",
+    "Each backend supports its own set of styling options. For example, Bokeh uses `line_dash`, while Matplotlib uses `linestyle`. hvPlot offers a compatibility mode that lets you use Bokeh-style options with Matplotlib, making it easier to reuse code across backends. Learn more in the [How-to guide on styling plots by backend](../how_to/style_plots_by_backend.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f3d4b164-7bcc-4fd2-ac83-f3a47274bf67",
+   "metadata": {},
+   "source": [
+    "## Limitations and Best Practices\n",
+    "\n",
+    "Not all options are supported across all backends, and some advanced features may only be available in specific libraries. For best results, use the backend-specific options for advanced customization, and refer to the [reference documentation](../ref/plotting_options/index.md) for details on available options.\n",
+    "\n",
+    "hvPlot's backend flexibility allows you to choose the best visualization library for your needs, while keeping your plotting code consistent and reusable.\n",
+    "\n",
+    ":::{admonition} Suggested Readings\n",
+    ":class: seealso\n",
+    "[Loading and switching plotting extensions](../how_to/load_switch_plotting_extensions.ipynb)\n",
+    "\n",
+    "[Styling plots by backend](../how_to/style_plots_by_backend.ipynb)\n",
+    "\n",
+    "[Plotting Options](../ref/plotting_options/index.md)\n",
+    ":::"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

doc/explanation/index.md

@@ -0,0 +1,11 @@
+# Explanation
+
+Explanation guides provide in-depth understanding of key concepts in hvPlot. These guides help you understand the reasoning behind design decisions and when to use different approaches.
+
+```{toctree}
+:titlesonly:
+:hidden:
+:maxdepth: 2
+
+hvplot_backend_support
+```

doc/how_to/index.md

@@ -0,0 +1,12 @@
+# How-To Guides
+
+How-to guides are practical, problem-oriented instructions that help you accomplish specific tasks with hvPlot. These guides assume you're already familiar with the basics and want to solve particular problems or achieve specific goals.
+
+```{toctree}
+:titlesonly:
+:hidden:
+:maxdepth: 2
+
+load_switch_plotting_extensions
+style_plots_by_backend
+```

doc/how_to/load_switch_plotting_extensions.ipynb

@@ -0,0 +1,138 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "98c86d5c",
+   "metadata": {},
+   "source": [
+    "# How to Load and Switch Plotting Extensions in hvPlot\n",
+    "\n",
+    "This guide shows how to load different plotting extensions in hvPlot and switch between them. hvPlot supports [Bokeh](https://docs.bokeh.org/) and [Matplotlib](https://matplotlib.org/) as backends for rendering plots."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "108ed881",
+   "metadata": {},
+   "source": [
+    "## Load hvPlot and a Sample Dataset\n",
+    "\n",
+    "We'll use the `penguins` dataset from the `hvsampledata` module for all examples."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "563a019f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hvplot.pandas\n",
+    "penguins = hvplot.sampledata.penguins('pandas').dropna()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3bc21afb",
+   "metadata": {},
+   "source": [
+    "## Load Matplotlib Extension\n",
+    "\n",
+    "By default, importing an accessor like `hvplot.pandas` loads the Bokeh extension. To use Matplotlib, call `hvplot.extension('matplotlib')`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6b0d85de",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hvplot.extension('matplotlib')  # Loads Matplotlib (active) extension."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8ac4fdc9",
+   "metadata": {},
+   "source": [
+    "## Plot with the Active Extension\n",
+    "\n",
+    "The following plot uses the currently active extension (Matplotlib):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "713ebc6f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', c='species', title='Penguins Bill Dimensions')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8aaf2d90",
+   "metadata": {},
+   "source": [
+    "## Switch Plotting Extension with `output()`\n",
+    "\n",
+    "You can switch the active backend using `hvplot.output(backend=...)`. Below, we switch between Matplotlib and Bokeh.\n",
+    "\n",
+    ":::{tip}\n",
+    "The `extension` function could also be used to switch the plotting extension. You should however prefer `output` as any call to `extension` actually internally loads code in the output of the cell where it is executed, which can significantly increase the notebook size if `extension` is called in multiple cells.\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c30e2d57",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', c='species', title='Penguins Bill Dimensions (Matplotlib)')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "06625de1",
+   "metadata": {},
+   "source": [
+    "Switching to Bokeh is as simple as calling `hvplot.output(backend='bokeh')`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6873b401",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hvplot.output(backend='bokeh')\n",
+    "penguins.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', c='species', title='Penguins Bill Dimensions (Bokeh)')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "80d0ad0b",
+   "metadata": {},
+   "source": [
+    "You can load multiple plotting extensions in hvPlot and switch between them using `hvplot.output()`. This allows you to choose the best backend for your visualization needs.\n",
+    "\n",
+    ":::{seealso}\n",
+    "[Styling plots with backend specific option](./style_plots_by_backend.ipynb)\n",
+    ":::"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}