Wrapper Kernel Auto Documentation

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+
+      - name: Build
+        run: mkdocs build --clean
+
+      - name: Publish to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site
+          destination_dir: ${{ github.event_name == 'push' && '' || format('pr-{0}', github.event.pull_request.number) }}
+          keep_files: true
+
+      - name: Comment preview URL on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request.number;
+            const url = `https://${context.repo.owner}.github.io/${context.repo.repo}/pr-${pr}/`;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr,
+              body: `Docs preview: ${url}`
+            });

.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 dist/
 build/
 *.egg
+
+# Documentation
+site/

docs/api/index.md

@@ -0,0 +1,30 @@
+---
+title: API Overview
+---
+
+# API Overview
+
+The Jumper Wrapper Kernel exposes a modular API organized into three main components:
+
+- **Kernel** - The main `JumperWrapperKernel` class that implements the Jupyter kernel protocol and manages kernel wrapping
+- **Installation** - Functions for installing and uninstalling the kernel specification
+- **Utilities** - Helper functions for magic command detection and cell routing
+
+## Architecture
+To be described
+
+## Message Flow
+
+1. Cell code arrives at `do_execute()`
+2. `_is_local_magic()` checks if code contains only local magic commands
+3. Local magics are executed via `_execute_local_magic()`
+4. Other code is forwarded via `_forward_to_wrapped_kernel()`
+5. Pre/post cell events are triggered for jumper-extension hooks
+
+## Module Reference
+
+For detailed API documentation, see:
+
+- [Kernel](kernel.md) - Main kernel class and magic commands
+- [Installation](install.md) - Kernel installation functions
+- [Utilities](utilities.md) - Magic detection helpers

docs/api/install.md

@@ -0,0 +1,17 @@
+---
+title: Installation
+---
+
+# Installation Module
+
+The installation module provides functions for installing and uninstalling the Jumper Wrapper Kernel specification.
+
+## Functions
+
+::: jumper_wrapper_kernel.install
+    options:
+      show_root_heading: false
+      members:
+        - install_kernel
+        - uninstall_kernel
+        - main

docs/api/kernel.md

@@ -0,0 +1,28 @@
+---
+title: Kernel
+---
+
+# Kernel Module
+
+The kernel module contains the main `JumperWrapperKernel` class and the `JumperWrapperMagics` class for magic command handling.
+
+## JumperWrapperMagics
+
+::: jumper_wrapper_kernel.kernel.JumperWrapperMagics
+    options:
+      show_root_heading: true
+      members:
+        - list_kernels
+        - wrap_kernel
+
+## JumperWrapperKernel
+
+::: jumper_wrapper_kernel.kernel.JumperWrapperKernel
+    options:
+      show_root_heading: true
+      members:
+        - do_execute
+        - do_shutdown
+        - do_complete
+        - do_inspect
+        - kernel_info

docs/api/utilities.md

@@ -0,0 +1,18 @@
+---
+title: Utilities
+---
+
+# Utilities Module
+
+The utilities module provides helper functions for detecting and classifying magic commands in cell content.
+
+## Functions
+
+::: jumper_wrapper_kernel.utilities
+    options:
+      show_root_heading: false
+      members:
+        - get_line_magics_cached
+        - is_known_line_magic
+        - is_pure_line_magic_cell
+        - is_local_magic_cell

docs/getting-started/installation.md

@@ -0,0 +1,64 @@
+---
+title: Installation
+---
+
+# Installation
+
+## Requirements
+
+- Python >= 3.8
+- ipykernel >= 6.0
+- jupyter_client >= 7.0
+- jumper-extension >= 0.3.0
+
+## Standard Installation
+
+Install the package from PyPI:
+
+```bash
+pip install jumper_wrapper_kernel
+```
+
+Then install the kernel specification:
+
+```bash
+python -m jumper_wrapper_kernel.install install
+```
+
+## Installation for Virtual Environments
+
+If you're using a virtual environment or conda, install to `sys.prefix`:
+
+```bash
+python -m jumper_wrapper_kernel.install install --sys-prefix
+```
+
+## Development Installation
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/ScaDS/jumper_wrapper_kernel.git
+cd jumper_wrapper_kernel
+pip install -e .
+python -m jumper_wrapper_kernel.install install
+```
+
+## Verification
+
+After installation, verify the kernel is available:
+
+```bash
+jupyter kernelspec list
+```
+
+You should see `jumper_wrapper` in the list of available kernels.
+
+## Uninstallation
+
+To remove the kernel:
+
+```bash
+python -m jumper_wrapper_kernel.install uninstall
+pip uninstall jumper_wrapper_kernel
+```

docs/getting-started/quickstart.md

@@ -0,0 +1,72 @@
+---
+title: Quickstart
+---
+
+# Quickstart
+
+This guide shows you how to use the Jumper Wrapper Kernel in a few simple steps.
+
+## Step 1: Select the Kernel
+
+1. Start Jupyter Notebook or JupyterLab
+2. Create a new notebook
+3. Select **Jumper Wrapper Kernel** as your kernel
+
+## Step 2: List Available Kernels
+
+See which kernels can be wrapped:
+
+```python
+%list_kernels
+```
+
+Output:
+```
+Available Jupyter Kernels:
+--------------------------------------------------
+  python3: Python 3 (ipykernel) (python)
+  ir: R (r)
+  julia-1.9: Julia 1.9 (julia)
+--------------------------------------------------
+```
+
+## Step 3: Wrap a Kernel
+
+Wrap your desired kernel:
+
+```python
+%wrap_kernel python3
+```
+
+Output:
+```
+Successfully wrapped kernel: python3
+Hint: Refresh the page (without restarting the kernel) to enable syntax highlighting for the wrapped language.
+```
+
+## Step 4: Use Performance Monitoring
+
+Now you can use jumper-extension commands while running code on the wrapped kernel:
+
+```python
+# Start monitoring (handled locally)
+%perfmonitor_start
+
+# Run code on the wrapped kernel
+import numpy as np
+x = np.random.rand(1000, 1000)
+y = np.dot(x, x.T)
+
+# View performance report (handled locally)
+%perfmonitor_perfreport
+```
+
+## How It Works
+
+The Jumper Wrapper Kernel acts as a proxy:
+
+1. **Magic commands** from jumper-extension are intercepted and executed locally
+2. **All other code** is forwarded to the wrapped kernel
+3. **Output** is streamed back to the notebook
+
+This allows you to monitor performance of any Jupyter kernel, regardless of its language.

docs/guides/magic-commands.md

@@ -0,0 +1,69 @@
+---
+title: Magic Commands
+---
+
+# Magic Commands
+
+The Jumper Wrapper Kernel provides its own magic commands for kernel management, plus full access to jumper-extension magic commands for performance monitoring.
+
+## Wrapper Magic Commands
+
+### `%list_kernels`
+
+Lists all available Jupyter kernels that can be wrapped.
+
+```python
+%list_kernels
+```
+
+Output:
+```
+Available Jupyter Kernels:
+--------------------------------------------------
+  python3: Python 3 (ipykernel) (python)
+  ir: R (r)
+  julia-1.9: Julia 1.9 (julia)
+--------------------------------------------------
+Currently wrapped kernel: python3
+```
+
+### `%wrap_kernel`
+
+Wraps an existing Jupyter kernel. All subsequent code (except local magic commands) will be forwarded to this kernel.
+
+**Basic usage:**
+
+```python
+%wrap_kernel python3
+```
+
+**With permanent kernel spec:**
+
+```python
+%wrap_kernel ir --save jumper-r
+```
+
+This creates a new kernel spec `jumper-r` that automatically wraps the R kernel on startup.
+
+## Jumper Extension Commands
+
+All jumper-extension magic commands are available and executed locally:
+
+| Command | Description |
+|---------|-------------|
+| `%perfmonitor_start [interval]` | Start performance monitoring |
+| `%perfmonitor_stop` | Stop performance monitoring |
+| `%perfmonitor_perfreport` | View performance report |
+| `%perfmonitor_plot` | Plot performance data |
+| `%cell_history` | View cell execution history |
+
+For complete documentation on jumper-extension commands, see the [jumper-extension documentation](https://scads.github.io/jumper_ipython_extension/).
+
+## Command Routing
+
+The kernel automatically routes commands:
+
+- **Local execution**: Wrapper magics and jumper-extension magics
+- **Forwarded to wrapped kernel**: All other code
+
+This routing is determined by analyzing the cell content before execution.

docs/guides/wrap-kernel.md

@@ -0,0 +1,23 @@
+# How to Wrap a new Kernel
+
+=== "Presentation"
+<iframe 
+    src="https://scribehow.com/embed/How_to_Wrap_a_Kernel_R_kernel_example__ezI7DbqeQ8uFkWjt-i34TA" 
+    width="800" 
+    height="679" 
+    allow="fullscreen" 
+    style="aspect-ratio: 1 / 1; 
+    border: 0; 
+    min-height: 480px">
+</iframe>
+
+=== "Video"
+<iframe 
+    src="https://scribehow.com/embed/How_to_Wrap_a_Kernel_R_kernel_example__ezI7DbqeQ8uFkWjt-i34TA?as=video" 
+    width="100%" 
+    height="800" 
+    allow="fullscreen" 
+    style="aspect-ratio: 16 / 12; 
+    border: 0; 
+    min-height: 480px">
+</iframe>