cmscom · terapyon · Dec 24, 2025 · Dec 22, 2025 · Dec 22, 2025 · Dec 22, 2025
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,81 @@
 # Changelog
 
+## 0.5.0 (2025-12-24)
+
+**Major Feature Release: NetworkX Plotter API** (terapyon)
+
+### New Features
+
+- **High-level Plotter API**: Direct NetworkX graph visualization without manual JSON conversion
+  - `Plotter.add_networkx()` method for seamless graph rendering in JupyterLab
+  - Support for all 4 NetworkX graph types: Graph, DiGraph, MultiGraph, MultiDiGraph
+  - Automatic node/edge extraction with attribute preservation
+
+- **Custom Styling Support**:
+  - Node color mapping via attribute names or callable functions
+  - Node label mapping with flexible attribute selection
+  - Edge label mapping for relationship visualization
+  - Automatic color scale detection (continuous vs. categorical)
+
+- **Layout Control**:
+  - 5 built-in layout algorithms: spring, kamada_kawai, spectral, circular, random
+  - Custom layout function support
+  - Existing position attribute detection
+  - Automatic fallback with NaN/inf validation
+
+- **Multi-Graph Type Support**:
+  - Edge direction preservation for DiGraph (via metadata)
+  - Edge key preservation for MultiGraph/MultiDiGraph
+  - Multiple edge expansion into independent Edge objects
+  - Automatic graph type detection and dispatch
+
+### API Examples
+
+```python
+from net_vis import Plotter
+import networkx as nx
+
+# Basic visualization
+G = nx.karate_club_graph()
+plotter = Plotter(title="Karate Club Network")
+plotter.add_networkx(G)
+
+# Custom styling
+plotter.add_networkx(G,
+    node_color="club",
+    node_label=lambda d: f"Node {d.get('name', '')}",
+    layout='kamada_kawai'
+)
+```
+
+### Implementation Details
+
+- **NetworkXAdapter**: 650+ lines of conversion logic with comprehensive type hints
+- **Test Coverage**: 60+ test methods covering all public APIs
+- **Python 3.10+ type hints**: Full type annotation support
+- **Comprehensive docstrings**: All public methods documented
+
+### Installation Options
+
+- **Basic**: `pip install net_vis` - Includes spring, circular, and random layouts
+- **Full**: `pip install net_vis[full]` - Includes all layouts (adds SciPy for kamada_kawai and spectral)
+
+### Dependencies
+
+**Core:**
+
+- NetworkX 3.0+
+- NumPy 2.0+ (required for layout algorithms)
+
+**Optional (installed with [full]):**
+
+- SciPy 1.8+ (required for kamada_kawai and spectral layouts)
+
+### Compatibility
+
+- JupyterLab: 3.x and 4.x
+- Python: 3.10+
+
 ## 0.4.0 (2025-11-21)
 
 **Major Release: Migration to MIME Renderer Architecture** (terapyon)

diff --git a/README.md b/README.md
@@ -1,24 +1,77 @@
 # netvis
 
-NetVis is a package for interactive visualization of Python NetworkX graphs within JupyterLab. It leverages D3.js for dynamic rendering and supports HTML export, making network analysis effortless.
+NetVis is a package for interactive visualization of Python NetworkX graphs within JupyterLab. It leverages D3.js for dynamic rendering and provides a high-level Plotter API for effortless network analysis.
 
-**Version 0.4.0** introduces a MIME renderer architecture that simplifies installation and improves compatibility with modern JupyterLab environments.
+**Version 0.5.0** introduces the NetworkX Plotter API, enabling direct visualization of NetworkX graph objects without manual JSON conversion.
 
 ## Installation
 
+### Basic Installation
+
 You can install using `pip`:
 
 ```bash
 pip install net_vis
 ```
 
-**Note for version 0.4.0+**: The nbextension is no longer required. NetVis now uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x environments.
+This provides core functionality with layouts: **spring**, **circular**, and **random**.
+
+### Full Installation (Recommended)
+
+For all layout algorithms including **kamada_kawai** and **spectral**:
+
+```bash
+pip install net_vis[full]
+```
+
+This installs optional dependencies (scipy) required for advanced layout algorithms.
+
+**Note**: NetVis uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x environments. No manual extension enabling is required.
 
 ## Quick Start
 
-This section provides a simple guide to get started with the project using JupyterLab.
+### NetworkX Plotter API (New in v0.5.0)
+
+The easiest way to visualize NetworkX graphs in JupyterLab:
+
+```python
+from net_vis import Plotter
+import networkx as nx
+
+# Create a NetworkX graph
+G = nx.karate_club_graph()
+
+# Visualize with one line
+plotter = Plotter(title="Karate Club Network")
+plotter.add_networkx(G)
+```
+
+#### Custom Styling
+
+Control node colors, labels, and layouts:
+
+```python
+# Color nodes by attribute, customize labels
+plotter = Plotter(title="Styled Network")
+plotter.add_networkx(
+    G,
+    node_color="club",              # Use 'club' attribute for colors
+    node_label=lambda d: f"Node {d.get('name', '')}",  # Custom labels
+    edge_label="weight",            # Show edge weights
+    layout='kamada_kawai'           # Choose layout algorithm
+)
+```
+
+#### Supported Features
+
+- **Graph Types**: Graph, DiGraph, MultiGraph, MultiDiGraph
+- **Layouts**: spring (default), kamada_kawai, spectral, circular, random, or custom functions
+- **Styling**: Attribute-based or function-based color/label mapping
+- **Automatic**: Node/edge attribute preservation in metadata
+
+### Low-Level API (Advanced)
 
-### Example
+For manual control over the visualization data structure:
 
 ```python
 import net_vis

diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -4,10 +4,31 @@ Examples
 
 This section contains examples of using NetVis for interactive graph visualization in JupyterLab.
 
-Basic Usage
------------
 
-The most basic usage of NetVis::
+NetworkX Plotter API (Recommended)
+-----------------------------------
+
+**New in v0.5.0**: The easiest way to visualize NetworkX graphs::
+
+    from net_vis import Plotter
+    import networkx as nx
+
+    # Create and visualize NetworkX graph
+    G = nx.karate_club_graph()
+    plotter = Plotter(title="Karate Club Network")
+    plotter.add_networkx(G)
+
+For comprehensive examples including custom styling, layouts, and multi-graph support, see the :ref:`NetworkX Plotter API notebook <networkx_plotter>` below.
+
+
+Low-Level API
+-------------
+
+For advanced control with manual JSON, you can use the low-level NetVis API:
+
+**Basic Usage**
+
+The most basic usage of the low-level API::
 
     import net_vis
 
@@ -63,7 +84,11 @@ NetVis can handle large graphs efficiently. The force-directed layout automatica
     For more examples, see the `examples directory <https://github.com/cmscom/netvis/tree/main/examples>`_ in the GitHub repository.
 
 
+Detailed Examples
+-----------------
+
 .. toctree::
-    :glob:
+    :maxdepth: 2
 
-    *
+    networkx_plotter
+    introduction
diff --git a/docs/source/examples/networkx_plotter.nblink b/docs/source/examples/networkx_plotter.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../examples/networkx_plotter.ipynb"
+}
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -4,9 +4,9 @@ net_vis
 
 Version: |release|
 
-NetVis is a package for interactive visualization of Python NetworkX graphs within JupyterLab. It leverages D3.js for dynamic rendering and supports HTML export, making network analysis effortless.
+NetVis is a package for interactive visualization of Python NetworkX graphs within JupyterLab. It leverages D3.js for dynamic rendering and provides a high-level Plotter API for effortless network analysis.
 
-**Version 0.4.0** introduces a MIME renderer architecture that simplifies installation and improves compatibility with modern JupyterLab environments.
+**Version 0.5.0** introduces the NetworkX Plotter API, enabling direct visualization of NetworkX graph objects without manual JSON conversion.
 
 
 Quickstart
@@ -16,7 +16,17 @@ To get started with net_vis, install with pip::
 
     pip install net_vis
 
-**Note**: As of version 0.4.0, NetVis uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x. Manual extension enabling is no longer required.
+**NetworkX Plotter API (New in v0.5.0)**::
+
+    from net_vis import Plotter
+    import networkx as nx
+
+    # Create and visualize NetworkX graph
+    G = nx.karate_club_graph()
+    plotter = Plotter(title="Karate Club Network")
+    plotter.add_networkx(G)
+
+**Note**: NetVis uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x. Manual extension enabling is not required.
 
 
 Contents

diff --git a/docs/source/installing.rst b/docs/source/installing.rst
@@ -4,19 +4,47 @@
 Installation
 ============
 
+Basic Installation
+------------------
 
 The simplest way to install net_vis is via pip::
 
     pip install net_vis
 
+This provides core functionality with the following layout algorithms:
+
+- **spring** (force-directed)
+- **circular**
+- **random**
+
+Full Installation (Recommended)
+--------------------------------
+
+For all layout algorithms including advanced options::
+
+    pip install net_vis[full]
+
+This installs optional dependencies (scipy) and enables additional layouts:
+
+- **kamada_kawai** (stress-minimization)
+- **spectral** (eigenvalue-based)
+
 **That's it!** As of version 0.4.0, NetVis uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x environments. No additional installation or configuration steps are required.
 
 
 Requirements
 ------------
 
+**Core Dependencies:**
+
 - Python 3.10 or later
 - JupyterLab 3.x or 4.x
+- NetworkX 3.0+ (automatically installed)
+- NumPy 2.0+ (automatically installed, required for layout algorithms)
+
+**Optional Dependencies (installed with [full]):**
+
+- SciPy 1.8+ (required for kamada_kawai and spectral layouts)
 
 **Note**: Jupyter Notebook Classic is no longer supported as of version 0.4.0. Please use JupyterLab instead.