joplin-plugin-jopyter 1.0.0

package/README.md

@@ -0,0 +1,282 @@
+# Jopyter Notebook - Joplin Plugin
+
+**Add runnable Python code blocks to your Joplin notes!** 
+
+Jopyter brings Jupyter notebook functionality directly into Joplin, allowing you to write, execute, and display Python code with rich output including plots, images, and formatted text right in your notes.
+
+## Features
+
+- **Execute Python code blocks** directly in Joplin notes
+- **Rich output support** including:
+  - Text output (stdout/stderr)
+  - Images and plots (matplotlib, seaborn, etc.)
+  - HTML and Markdown rendering
+  - Error handling with full tracebacks
+- **Multiple execution modes**:
+  - Run all Python blocks in a note
+  - Run the current block (cursor-based)
+  - Run specific blocks with custom kernels
+- **Persistent kernels** for maintaining variable state between executions
+- **Keyboard shortcuts** for quick execution
+- **Context menus** and toolbar integration
+- **Customizable settings** for Python path and kernel configuration
+- **Automatic demo notebook** with comprehensive examples and tutorials
+
+## Prerequisites
+
+Before using Jopyter, ensure you have:
+
+1. **Python 3.6+** installed on your system
+2. **Required Python packages**:
+   ```bash
+   pip install jupyter_client ipykernel
+   ```
+
+## Installation
+
+1. Download the latest `.jpl` file from the [releases page](https://github.com/Dubascudes/JopyterPlugin/releases)
+2. In Joplin, go to **Tools → Options → Plugins**
+3. Click **Install from file** and select the downloaded `.jpl` file
+4. Restart Joplin
+5. **Demo notebook**: A "Jopyter Notebook" folder will be automatically created at the top level with a comprehensive demo note containing examples and tutorials
+
+## Configuration
+
+After installation, configure Jopyter:
+
+1. Go to **Tools → Options → Plugins → Jopyter**
+2. Set the following options:
+   - **Python executable**: Path to your Python interpreter (e.g., `/usr/bin/python3`)
+   - **Default kernel name**: Kernel name to use (default: `python3`)
+   - **Working directory**: Optional working directory for code execution
+
+### Platform-Specific Python Paths
+
+- **Linux**: `/usr/bin/python3` or `~/miniconda3/envs/myenv/bin/python`
+- **macOS**: `/opt/homebrew/bin/python3` or `/usr/local/bin/python3`
+- **Windows**: `C:\Users\you\miniconda3\envs\myenv\python.exe`
+
+## Usage
+
+### Creating Python Code Blocks
+
+#### Method 1: Using the Menu
+1. Place your cursor where you want the code block
+2. Go to **Tools → Jopyter → Insert Python code block**
+3. Or use the keyboard shortcut: `Ctrl+Alt+P` (Windows/Linux) or `Cmd+Alt+P` (macOS)
+
+#### Method 2: Manual Creation
+Create a code block with the following syntax:
+````markdown
+```python kernel=python3
+# Your Python code here
+print("Hello, Jopyter!")
+```
+````
+
+### Executing Code
+
+#### Run All Python Blocks
+- **Menu**: Tools → Jopyter → Run all Python blocks
+- **Toolbar**: Click the Python icon in the editor toolbar
+- **Keyboard**: Use the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+
+#### Run Current Block
+- **Keyboard**: `Ctrl+Shift+Enter` (Windows/Linux) or `Cmd+Shift+Enter` (macOS)
+- **Context Menu**: Right-click in a Python block → "Run current Python block"
+- **Menu**: Tools → Jopyter → Run current Python block
+
+### Advanced Features
+
+#### Custom Kernels
+Specify different kernels for different code blocks:
+````markdown
+```python kernel=myenv
+import pandas as pd
+# This uses the 'myenv' kernel
+```
+````
+
+#### Working Directory
+Set a custom working directory in the plugin settings to run code from a specific location.
+
+#### Rich Output Examples
+````markdown
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Create a simple plot
+x = np.linspace(0, 10, 100)
+y = np.sin(x)
+plt.plot(x, y)
+plt.title('Sine Wave')
+plt.show()
+```
+````
+
+### Managing Outputs
+
+- **Clear all outputs**: Tools → Jopyter → Clear all Jopyter outputs in note
+- **Restart kernel**: Tools → Jopyter → Restart Python kernel
+- **Create demo notebook**: Tools → Jopyter → Create Jopyter demo notebook (creates the tutorial notebook)
+- **Force create demo notebook**: Tools → Jopyter → Force create Jopyter demo notebook (recreate) (deletes existing and creates fresh)
+- **Find demo notebook location**: Tools → Jopyter → Find Jopyter demo notebook location (shows where the notebook is located)
+- **Open demo notebook**: Tools → Jopyter → Open Jopyter demo notebook (opens the demo note)
+
+## Screenshots
+
+To help users understand how to use Jopyter, please take the following screenshots:
+
+### 1. Plugin Installation
+**File**: `screenshots/installation.png`
+- Screenshot of Joplin's plugin installation dialog
+- Show the "Install from file" button and file selection
+
+### 2. Plugin Settings
+**File**: `screenshots/settings.png`
+- Screenshot of Tools → Options → Plugins → Jopyter
+- Show the three configuration fields:
+  - Python executable path
+  - Default kernel name
+  - Working directory
+
+### 3. Menu Integration
+**File**: `screenshots/menu.png`
+- Screenshot of the Tools → Jopyter menu
+- Show all available commands:
+  - Insert Python code block
+  - Run all Python blocks
+  - Run current Python block
+  - Restart Python kernel
+  - Clear all Jopyter outputs in note
+
+### 4. Toolbar Button
+**File**: `screenshots/toolbar.png`
+- Screenshot of the editor toolbar
+- Highlight the Python icon button for running all blocks
+
+### 5. Context Menu
+**File**: `screenshots/context-menu.png`
+- Screenshot of right-clicking in a Python code block
+- Show the context menu options for Jopyter
+
+### 6. Basic Code Execution
+**File**: `screenshots/basic-execution.png`
+- Screenshot of a simple Python code block before execution
+- Show the code and the output after running
+
+### 7. Rich Output Example
+**File**: `screenshots/rich-output.png`
+- Screenshot showing matplotlib plot output
+- Include both the code block and the rendered plot
+
+### 8. Error Handling
+**File**: `screenshots/error-handling.png`
+- Screenshot of a Python code block with an error
+- Show the error output with traceback
+
+### 9. Multiple Code Blocks
+**File**: `screenshots/multiple-blocks.png`
+- Screenshot of a note with multiple Python code blocks
+- Show different execution states (some run, some not)
+
+### 10. Keyboard Shortcuts
+**File**: `screenshots/keyboard-shortcuts.png`
+- Screenshot of Joplin's keyboard shortcuts settings
+- Highlight the Jopyter-specific shortcuts
+
+## Keyboard Shortcuts
+
+| Action | Windows/Linux | macOS |
+|--------|---------------|-------|
+| Insert Python code block | `Ctrl+Alt+P` | `Cmd+Alt+P` |
+| Run current Python block | `Ctrl+Shift+Enter` | `Cmd+Shift+Enter` |
+
+## Troubleshooting
+
+### Plugin Crashes on Startup
+If Joplin crashes when starting with Jopyter enabled:
+
+1. **Check Python installation**: Ensure Python 3.6+ is installed
+2. **Install required packages**:
+   ```bash
+   pip install jupyter_client ipykernel
+   ```
+3. **Verify Python path**: Check that the Python executable path in settings is correct
+4. **Check Joplin logs**: Enable developer tools (Help → Toggle Developer Tools) to see error messages
+
+### Code Execution Issues
+- **Module not found**: Install required Python packages in your environment
+- **Permission errors**: Check that the working directory is accessible
+- **Kernel issues**: Try restarting the kernel or using a different kernel name
+
+### Output Not Displaying
+- **Images not showing**: Ensure matplotlib/seaborn plots use `plt.show()`
+- **HTML not rendering**: Check that the output is valid HTML
+- **Text formatting**: Use proper markdown syntax in your output
+
+## Development
+
+### Building from Source
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Dubascudes/JopyterPlugin.git
+   cd JopyterPlugin
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Build the plugin:
+   ```bash
+   npm run dist
+   ```
+
+4. The built plugin will be in the `publish/` directory
+
+### Project Structure
+
+```
+src/
+├── index.ts          # Main plugin logic
+├── editor.ts         # CodeMirror editor integration
+├── manifest.json     # Plugin manifest
+└── python/
+    └── bridge.py     # Python-Jupyter bridge script
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/Dubascudes/JopyterPlugin/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/Dubascudes/JopyterPlugin/discussions)
+- **Website**: [willenglish.tech](https://willenglish.tech/)
+
+## Changelog
+
+### v1.0.0
+- Initial release
+- Basic Python code execution
+- Rich output support
+- Multiple execution modes
+- Keyboard shortcuts and context menus
+- Customizable settings
+
+---
+
+**Made with ❤️ for the Joplin community**

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "joplin-plugin-jopyter",
+  "version": "1.0.0",
+  "scripts": {
+    "dist": "webpack --env joplin-plugin-config=buildMain && webpack --env joplin-plugin-config=buildExtraScripts && webpack --env joplin-plugin-config=createArchive",
+    "prepare": "npm run dist",
+    "updateVersion": "webpack --env joplin-plugin-config=updateVersion",
+    "update": "npm install -g generator-joplin && yo joplin --node-package-manager npm --update --force"
+  },
+  "license": "MIT",
+  "keywords": [
+    "joplin-plugin"
+  ],
+  "files": [
+    "publish"
+  ],
+  "devDependencies": {
+    "@types/node": "^18.7.13",
+    "chalk": "^4.1.0",
+    "copy-webpack-plugin": "^11.0.0",
+    "fs-extra": "^10.1.0",
+    "glob": "^8.0.3",
+    "tar": "^6.1.11",
+    "ts-loader": "^9.3.1",
+    "typescript": "^4.8.2",
+    "webpack": "^5.74.0",
+    "webpack-cli": "^4.10.0"
+  }
+}

package/publish/tech.willenglish.jopyter.json

@@ -0,0 +1,18 @@
+{
+	"manifest_version": 1,
+	"id": "tech.willenglish.jopyter",
+	"app_min_version": "3.3",
+	"version": "1.0.0",
+	"name": "Jopyter Notebook",
+	"description": "Add runnable Python code blocks to your notes!",
+	"author": "William English",
+	"homepage_url": "https://willenglish.tech/",
+	"repository_url": "https://github.com/Dubascudes/JopyterPlugin",
+	"keywords": [],
+	"categories": [],
+	"screenshots": [],
+	"icons": {},
+	"promo_tile": {},
+	"_publish_hash": "sha256:b32445784014218bbd5216046bfd1968909f76f18d26f2fe646cd03cb99ec4c5",
+	"_publish_commit": "main:718af781dfe739b099ece40e243d4898ad11a63c"
+}